
August 1991 
$4.50 US 

Canada $5.95 


THE JOURNAL FOR ADVANCED PC 


Graphical 

User 

Interfaces 


■ Data Windows 
for PM 

■ TEGLGUI 
for DOS 


Windows 

Development 

■ Serial 

Communications 

■ MultiScope 
Debuggers 

I 

PLUS: 

■ Interrupts 
from BASIC 

■ Writing 

Device Drivers in C , a 




Introducing software 
testing the easy way! 


Why every developer needs Ghost — 
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F YOU WANT TO 

GET the bugs out of 
your software and 
keep them out, Ghost 
is just what you’re looking for! It’s a 
breakthrough product that finally 
makes it practical for developers and 
testers like you to do extensive, - 
repetitive regression testing 
throughout the entire development 
cycle - all automatically! 

That’s right. At last there’s an 
easy way to end the testing 
nightmare that’s been driving 
you crazy. No matter what 
language you program in, 

Ghost can help you deliver 
high-quality, reliable 
software without the 
hassle. We guarantee it! 

Ghost makes exact recordings 
of your software test sequences and 
screen displays, so you can rerun 
them and compare the results auto¬ 
matically whenever needed. Ghost 
will: 

♦ Document program errors au¬ 
tomatically. 

♦ Make testing grow more complete 
over time. 

♦ Shorten the critical integration 
and testing phase of develop¬ 
ment. 

♦ Lessen the chance of that “last- 
minute fatal bug.” 

♦ Make regression testing for new 
releases a practical reality. 


Meet Ghost Jr. 

Ghost Jr. is a limited-capability ver¬ 
sion of Ghost that provides full 
keyboard and screen recording, but 
has no playback capability. This 
low-priced version makes it practical 
to give copies to 
everyone who tests 
your product - even 
end users. All the 
problems they en¬ 
counter will be docu¬ 
mented by Ghost 
scripts. Think of how 
this will speed up your 
debugging and testing 
cycles! 



The price 
is right and you 
don’t risk a thing! 

Ghost costs just $195 and comes 
with a 90-day money-back guar¬ 
antee. Ghost Jr. costs just $79 and 
steep quantity discounts are avail¬ 
able. Don’t miss this chance to end 
the tedium of software testing. Pick 
up the phone and order right now! 


Ghost 
at a glance. 

Ghost provides you with a way of 
making exact recordings of your 
software test sequences and screen dis¬ 
plays in a machine readable form. 

♦ 

You can then re-execute any set of 
tests at high speed without the man¬ 
ual labor that’s normally required. 

♦ 

You can interactively view all the dif¬ 
ferences found in the screen displays 
between the two runs, or have them 
printed out in a handy report. 

♦ 

Requires no program changes 
or special hardware! 

_ Uses only 16K of memory! 


MONEY-BACK 

GUARANTEE 

If you’re dissatisfied with 
Ghost or Ghost Jr. for any 
reason, return them within 
90 days of purchase for a 
prompt, friendly, no-ques - 
Pons-asked refund. 


TO ORDER 

or for more information, call toll-free: 
( 800 ) 848-1248 
International: (802) 848-7731 
Fax: (802) 848-3502 

Vermont Creative Software, Pinnacle Meadows 
Richford, VT05476 U.S.A. 

Please mention Offer 156. 
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Ghost. So good at getting rid of the bugs, it’s scary. 
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“Who would you expect to give 
you the best compiler for creating 
Windows applications?” 

—Answer below 


Introducing a vastly superior way to write applications 
for Microsoft® Windows. New Borland® C++. The only 
complete C and C++ programming environment for 
Windows and DOS. Borland C++ generates Windows 
applications and DLLs, supports Windows debugging, 
and includes a visual resource editor. So you don’t need 
to buy the Microsoft Windows Software Development 
Kit (SDK). 

Borland C++ is from the people who know what 
professional programmers want. In fact, Turbo C++ 
Professional (the predecessor to Borland C++) won both 
PC Magazine’s 1990 Technical Excellence Award and 
BYTE’s 1990 Award of Excellence. 

Designed for professionals 
by professionals 

Every copy of Borland C++ comes with: 

• ANSI C compiler and C++ compiler 

• Turbo Drive™ compiler and integrated development 
environment running in protected mode for huge 
capacity 

• Precompiled headers that significantly increase 
recompilation speed 

• Turbo Debugger® for Windows and DOS 

• Whitewater™ Resource Toolkit for visually creating 
icons, dialogs, bitmaps and menu bars 

• Turbo Profiler™ and Turbo Assembler® 

Answer: 


Compare these costs 



Microsoft® C 6.0 

Borland C++ 

C compiler 

$ 495 

$495 

C++ compiler 

not available 

included 

Windows programming 
tools 

$ 495* (SDK) 

included 

Assembler 

$ 150 

included 

Programming Windows 

$ 30 

included 

Total 

$1,170 

$495** 


Buy now! 

Get "Programming Windows” free! 

Buy Borland C++ now from your local dealer and 
get a free copy of Programming Windows by 
Charles Petzold, the best-selling book about learning 
Windows programming.! 

Special upgrade pricing is available from Borland for 
owners of Turbo C,® Turbo C® Professional, Turbo C++ 
and Turbo C++ Professional. 

See your dealer 
today, or 
call Borland to 
upgrade at 
1-800-331-0877 



a n v l a o a 

___ The Leader in Object-Oriented Programming for Windows and DOS 

| CODE: MC79] 

’Effective price is $254 if SDK is purchased bundled with Microsoft C. **$495 is the suggested retail price. tOffer good in U.S. and Canada while supplies last. Upgrade customers not eligible for free book. Copyright © 1991 Borland Bl 1397A 
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From 

The Editor 

User interfaces have come a long way, but they still have a long way to go. The boundary 
between humans and automata, the user interface, involves enough complex issues to keep us 
all employed for decades to come. Some recent incidents have given me pause to consider 
how much and how little improvement we've seen in computer-human interfaces. 

In the last stage of editing an article, I use a Windows program to help locate spelling and 
grammatical errors. The core of the program is wonderful - it is completely tailorable and can 
detect a wide variety of problems. The user interface, unfortunately, is atrocious. The program 
hogs the CPU and doesn't even bother to change the cursor into an hourglass. Most of the 
windows take up most of the screen and aren't scrollable. That means that if you shrink a 
window, you may have to restore it to full size to see text or press a button. The manufacturer 
obviously did a quick port of their DOS version to try to capitalize on the success of Windows. 

This program sunk home to me the fact that user interface standards and guidelines can’t 
prevent companies from producing poor user interfaces. During a recent editing session, the 
program finished checking a document and then solicitously asked me if I wanted to save my 
changes. I clicked the mouse on the OK button and there was a pause, so I clicked the mouse 
on the next couple of actions I wanted to take. Unfortunately, under some conditions, the 
program asks you three times (with three slightly different dialog boxes) if you want to save 
your changes. When I thought I was clicking my next actions, I was actually clicking cancel 
buttons that told the program not to save my changes after all. 

I was stunned. My work for that 30-minute session was completely lost. Much later, I 
realized that my shock was due to the fact that user interfaces have improved greatly over the 
years. Ten years ago, I saved my work every few minutes and I would have laughed at anyone 
foolhardy enough to work for half an hour without saving to disk. I see that I now trust other 
people's software to an amazing degree. I actually assume that commercial software will “do 
the right thing," whereas I used to assume software would do the wrong thing at the most 
inopportune moment User interfaces really are getting better. 

On the other hand, if some user interfaces haven't improved, it may be because the 
software is 10 years old. Mailing lists, for example, are often still processed on mainframes fed 
by nine-track tapes. An envelope recently appeared in my post office box, addressed to Burk 
Labs (the name of my tiny company), from some sort of "Who's Who in The Computer In¬ 
dustry" organization. I was gratified that someone, perhaps many people, had recognized my 
accomplishments and nominated me for such an honor. When I read the salutation, however, I 
was quickly brought back down to earth. It read “Dear Mr. Labs.” 

My favorite mailing list nemesis is a C++ newsletter I subscribe to. I paid for my initial 
subscription with a check that has my name printed legibly at the top, but the newsletter 
came addressed to “Ron Burck.” They gave their mailing list to other companies and my box 
was soon filled with mail from C++ companies addressed to “Mr. Burck.” I knew this was the 
fault of mindless software, so I appealed directly to the human element with a handwritten 
note asking them to spell my name correctly and included a tried-and-true mnemonic device: 
“Burk is a four-letter word.” No dice. Obviously, someone on the newsletter's staff has found a 
spelling that they like and they plan to stick with it. I have one last trick up my sleeve, though: 
I plan to let my subscription expire and re-subscribe under my correct name. 

Hardware engineers can measure progress in MIPS. Software engineers can measure 
progress in defects per thousand lines of code. How can you objectively measure progress in 
computer-human interaction? Personally, I’ll know computers are fit to interact with humans 
the day they start spelling my name right. 

Ron Burk 



Editor 

















Fast code. 


SpontaneousAssembty 


ASSEMBLY LANGUAGE LIBRARY 



Absolutely nothing matches the speed and efficiency of assembly 
language. And nothing lets you code in assembly as fast as 
Spontaneous Assembly, the complete assembly language library. 
With MASM 5.1 or TASM, Spontaneous Assembly makes programming 
in assembly as fast and easy as coding in a high-level language— 
without the overhead. 

Over 700 ready-to-use functions and macros. 

Spontaneous Assembly puts a wealth of well-documented assembly 
routines at your fingertips, including • A complete high-speed 
windowing system (4.5K) • Near/far/relative heap management 
(650 bytes) • Direct/BIOS/DOS screen I/O (2.5K) • Array management, 
sorting, and searching (400 bytes) • Character/numeric/string 
conversion • Date and time manipulation • Critical error management 

• 32/64 bit integer math 

• Program and environment 
control • Enhanced DOS 
file I/O • File and directory 
management • String and 
memory manipulation • Full 
Microsoft/Borland memory 
model support • and much 
more—all royalty-free. 


Clear, complete documentation. 

A 750 page reference manual describes every function, macro, and 
variable in detail. Step-by-step instructions and technical notes explain 
integration with C, library customization, memory models, and more. 

Full source code. Toll-free support. 

Spontaneous Assembly includes nearly 60,000 lines of fully-commented 
assembly language source code. And toll-free support is available to 
all registered customers. 

Spontaneous Assembly. Guaranteed. 

See for yourself just how fast and easy assembly language programming 
can be. Order Spontaneous Assembly now from your dealer or call 
1-800-ASSEMBLY (1-800-277-3625) to order direct. Then try it for 30 days. 
If you’re not 100% satisfied, return it for a full refund! 

1-800-ASSEMBLY 

ORDERS • INFORMATION • SUPPORT 


Spontaneous Assembly is also available from: 
Programmer’s Paradise • Programmer’s Connection 
Programmer’s Warehouse • Programmer’s Shop 



For 80x86-based systems running DOS 2.0 or later. MASM 5.1 or TASM recommended. 

Base Two Development • A Division of Acclaim Technologies, Inc. • 11 East 200 North • Orem, Utah 84057 • (801) 222-9500 • FAX (801) 222-9521 
International Dealers: AUSTRALIA Interplex Software (02) 906 7066 BELGIUM Meta Logix 32-(0)3-829 05 81 CANADA SoftChoice (416) 322-7638 
FRANCE Micro Sigma 33-1-46.22.99.88 GERMANY AMON RF. 089-260-4849 Siener Soft 06126/595-0 JAPAN Toyo Engineering Corp. (03) 222-0541 
NETHERLANDS Lemax 02968-94 210 NEW ZEALAND PC Power 64-9-529-0200 SWEDEN LinSoft + 46 13 111588 TAIWAN Pronet (02)5523277 
UNITED KINGDOM Software Construction Company + 44 763 244114 

Spontaneous Assembly and Base Two Development are trademarks of Acclaim Technologies, Inc. 
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A Data Entry 
Window Class 
For OS/2 PM 

Piers Cherry! 


This article explains the need a special form window class and presents a 
detailed implementation in C. The accompanying listings include a simple 
demonstration program. The principles involved could also be applied to a 
Microsoft Windows implementation. 

Presentation Manager And CUA 

IBM's Common User Access (CUA) interface design guide explains that applica¬ 
tions should interact with the user primarily through sizeable, scrollable win¬ 
dows. However, Presentation Manager only provides high-level functions for 
creating frames to go around these windows. It doesn't help with the contents 
of the window itself, which the programmer must fill using graphics primitives or 
child windows. 

Presentation Manager does help with user interaction using a dialog box, 
generally displayed in response to a menu selection. However, CUA emphasizes 
that a dialog box should be used only to gather information from a user to 
perform a requested action. It should not be used for general-purpose data 
entry, which unfortunately is frequently required for most commercial applica¬ 
tions. 

You can put a size border around a dialog box in the 
Microsoft/IBM SDK screen painter, DLGBOX.EXE, but such a 
simple approach is insufficient. The implementation of 
dialog boxes does without a true client window, placing all 
the dialog controls directly on top of the underlying frame. 
When you shrink the frame window, the controls overlap 
the size border painted around its edges. Even if you inter¬ 
cept the paint message for the dialog box and do some 
fancy coding, it is virtually impossible to get satisfactory 
display updates under all circumstances. 



Piers Cherryl is a consultant specializing in OS/2 PM. 
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Listing 1 (form.h) 

/* replacement for WinLoadDlgO */ 

HWND EXPENTRY FormLoad( HWND hwndParent, HWND hwndOwner, PFNWP pfnwp, 

HMODULE hmod, USHORT idResources, PVOID p ); 

/* replacement for WinCreateDlgO 

- also needs module and resource id for icon, menu and/or acceltable */ 

HWND EXPENTRY FormCreate( HWND hwndParent, HWND hwndOwner, PFNWP pfnwp, 
PDLGTEMPLATE pDlgTemplate, HMODULE hmod, 

USHORT idResources, PVOID p ); 

/* replacement for WinEnumDlgItem() */ 

HWND EXPENTRY FormEnumItem( HWND hwndForm, HWND hwnd, USHORT code, BOOL fLock); 

/* replacement for WinDefDlgProcO */ 

MRESULT EXPENTRY wpForm( HWND, USHORT, MPARAM, MPARAM ); 

/* Utility routine to fetch the latest PM error and 
display it in a message box 

*/ 

void EXPENTRY ErrorInfoMessageBox( HAB hab, HWND hwnd, PSZ pszTitle ); 

/*END*/ 


Prototypes for "Form" Windows 


Listing 2 iform.c) 

/* 

A CUA compliant window class for data entry. 

Uses dialog templates created with the resource compiler (rc), 
or the OS/2 SDK screen painter (dlgbox). 

NB: Unlike a dialog box, a form has a true client window which 
owns the data entry control windows. 

*/ 

♦include <stdlib.h> /* for calloc() and free() */ 

♦define INCL_DOSRESOURCES /* For DosGetResourceQ */ 

♦define INCL_WIN 
♦include <os2.h> 

♦include “form.h" 

extern HAB hab; /* Under OS/2 1.2 you could use 
WinQueryAnchorBlock( HWND ) */ 

static MRESULT EXPENTRY wpFormFrame( HWND, USHORT, MPARAM, MPARAM ); 

HWND EXPENTRY FormLoad( HWND hwndParent, HWND hwndOwner, PFNWP pfnwp, 
HMODULE hmod, USHORT id, PVOID p ) 

{ 

SEL sel; 

HWND hwnd = NULL; 

if (!DosGetResource( hmod, RT_DIALOG, id, &sel )) 

{ 

hwnd * FormCreate( hwndParent, hwndOwner, pfnwp, 

MAKEP( sel, 0 ), hmod, id, p ); 

DosFreeSeg( sel ); 

} 

return hwnd; 


♦define LINE_SIZE 8 /* Number of pels to move on scroll by line */ 

♦define BORDER_SIZE 4 /* Whitespace to be left round edges of form */ 
♦define QWS_CXFORM (2*sizeof(PVOID)) 

♦define QWS_CYFORM (2*sizeof(PV0ID)+sizeof(USH0RT)) 

static void set_scrollbars( HWND hwnd, 

SHORT cxClient, SHORT cyClient ); 

HWND EXPENTRY FormCreate( HWND hwndParent, HWND hwndOwner, 

Implementation of “Form" Window Functions 
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Listing 2 - Cont’d 

PFNWP pfnwp, PDLGTEMPLATE pDlgTemplate, 

HMODULE hmod, USHORT id, PVOID p ) 

static BOOL flnitialized; 

USHORT i; 

HWND hwndFrame, hwnd; 

HWND hctl=NULL; /* default control to start with focus */ 

FRAMECDATA fcdata; /* holds parameters used 

to create a frame window */ 

PSZ pszTitle; 

HWND *pahwnd; /* pointer to array of control window handles */ 

POINTL aptl[2]; 

DLGTITEM *pDlgItem = &pDlgTemplate->adlgti[ 0 ]; 

USHORT cxClient, cyClient; 

RECTL rclForm; 

if (!fInitialized) 

{ 

flnitialized = TRUE; 

♦define CLASS_NAME "FORM" /* any unique name will do */ 
WinRegisterClass( hab, CLASS_NAME, wpForm, 0, 

2*sizeof(PV0ID)+2*sizeof(USHORT) ); 

) 

fcdata.cb = sizeof fcdata; /* initialization required by PM */ 
fcdata.flCreateFlags = 

*(PUL0NG)((PBYTE)pDlgTemplate + 

pDlgTemplate->adlgti[0].offCtlData)| 

FCF_TITLEBAR | FCF_SYSMENU | FCF_SIZEB0RDER | 

FCF_HORZSCROLL | FCF_VERTSCROLL; 
fcdata.hmodResources = hmod; 
fcdata.idResources = id; 

pszTitle = (PSZ)pDlgTemplate + pDlgTemplate->adlgti[ 0 ].offText; 
if (!*pszTitle) /* if no text for title bar */ 

pszTitle = "(Untitled)"; /* provide something */ 

aptl[0].x « pDlgItem->x; /* read size and position of form */ 
aptl[0].y « p01gltem->y; /* from first DLGTITEM structure */ 
aptl[l].x = p01gltem->cx; 
aptl[1].y = p01gltem->cy; 

/* convert from dialog units to pels */ 

WinMapDlgPoints( hwndParent, aptl, 2, TRUE ); 
cxClient = (USHORT)aptl[1].x; 
cyClient = (USHORT)aptl[1].y; 

/* inflate the frame window to accomodate controls around the form */ 
aptl[0].x -= WinQuerySysValue( HWND_DESKTOP, SV_CXSIZEBORDER ); 
aptl[0].y -= WinQuerySysValuej HWND_DESKTOP, SV_CYSIZEBORDER ); 
aptl[0].y -= WinQuerySysValuej HWND_DESKTOP, SV_CYHSCROLL ); 

aptl[1].x += 2 * WinQuerySysValue( HWND_DESKT0P, SV_CXSIZEBORDER ); 
aptl[1].x += WinQuerySysValue( HWN0_DESKT0P, SV_CXVSCROLL ); 

aptl[1].y += 2 * WinQuerySysValue( HWND_DESKTOP, SV_CYSIZEBORDER ); 
aptl[1].y += WinQuerySysValue( HWND_DESKTOP, SV_CYTITLEBAR ); 
aptl[1].y +- WinQuerySysValuej HWND_DESKTOP, SV_CYHSCROLL ); 

if (fcdata.flCreateFlags & FCF_MENU) 

aptl[1].y += WinQuerySysValue( HWND_DESKTOP, $V_CYMENU ); 

hwndFrame = WinCreateWindow( hwndParent, WC_FRAME, pszTitle, 

0, 0, 0, 0, 0, hwndOwner, HWND_T0P, id, 

&fcdata, 0 ); 

if (!hwndFrame) 

( 

/* display PM error message */ 

ErrorInfoMessageBox( hab, hwndParent, "Form creation error" ); 
return NULL; 

) 

hwnd = WinCreateWindow( hwndFrame, CLASS_NAME, 0, 0, 0, 0, 0, 0, 0, 
HWND_T0P, FID_CLIENT, 0,0); 

WinSetWindowPos( hwndFrame, HWND_T0P, 

(SHORT)aptl [0] .x, (SHORT)aptl[0].y, 
jsHORT)aptl[1].x, jsHORT)aptl[1].y, 

SWP_SIZE | SWP_M0VE ); 


A little-publicized solution has been 
around for some time. In early 1989, 
IBM’s International Technical Support 
Center in Boca Raton, FL, prepared and 
published a technical bulletin on PM ap¬ 
plication design. In an appendix, they 
provided a set of utility functions for 
creating and animating sizeable, scroll¬ 
able data entry screens, but they re¬ 
quire coding individual controls by hand 
- a tedious process and a significant 
step backwards from using DLGBOX.EXE. 
The listings accompanying this article 
present an alternative that uses window 
templates from a resource file as 
created by DLGBOX. EXE, but without the 
limitations of PM dialog box support. 

The Form API 

The form API comprises only four 
functions: FormLoad(), FormCreate (), 
FormEnumltemO , and wpForm(). 
Prototypes for these functions are 
defined in FORM. H (Listing 1) and the im¬ 
plementation is in FORM. C (Listing 2). The 
first three of these are analogous to 
UinCreateDlgf), UinLoadDlg() , and 
WinEnumDlgItem() respectively, wp- 
Form() is a replacement for UinDefDlg- 
Proc() as a default message handler in 
form window procedures. FORM.C does 
not provide an equivalent of UinDlg- 
Box() because primary and secondary 
CUA windows are almost invariably 
modeless. If you want to present a 
modal form you can use the construct: 

hwndForm = FormCreatej ... ); 
usResult = WinProcessDlgj hwnd¬ 
Form ); 

WinDestroyWindowj hwndForm ); 

In this case you would use Win- 
DismissDlgO within the form proce¬ 
dure, but l will emphasize that modeless 
windows are preferable. 

The initialization routine at the top of 
FormCreate() assumes the application’s 
anchor block handle from Uin- 
Initialize() is a global. You can work 
around this by breaking out the in¬ 
itialization code into a seperate function 
that your program calls explicitly when 
it starts up. OS/2 vl.2 now has a func¬ 
tion, UinQueryAnchorBlock() , that you 
could use instead. 

The main entry point FormLoadf) 
takes the same parameters as UinLoad- 
Dlg(). FormLoad() loads a dialog 
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pahwnd = (HWND*)cal1oc( pDlgTemplate->adlgti [ 0 ].cChildren+1, 
sizeof(HWND) ); 

WinSetWindowPtr( hwnd, QWL_USER+sizeof(PVOID), pahwnd ); 

rclForm.xLeft * rclForm.xRight « 

rclForm.yBottom » rclFora.yTop = 0; 

/* create the child control windows */ 

for (i = 1; i <= pDlgTemplate->adlgti[ 0 ].cChildren; i++) 

f 

pDlgltem = &pDlgTemplate->adlgti[ i ]; 

aptl[0].x = pDlgItem->x; 
aptl[0].y = pDlgItem->y; 
aptl[l].x = pDlgItem->cx; 
aptl[l].y = pDlgItem->cy; 

WinMapDlgPoints( hwnd, aptl, 2, TRUE/*Convert du to pels*/ ); 

pahwnd[ i-1 ] * WinCreateWindow( hwnd, 
pDlgItem->offClassName < 10 ? 

/* Stock class or user defined? */ 

(PSZ)(OxFFFFOOOO | (LONG)pDlgItem->offClassName): 
(PSZ)pDlgTemplate + pDlgItem->offClassName, 
(PSZ)pDlgTemplate + pDlgItem->offText, 
pDlgItem->flStyle, 

(SHORT)aptl[0].x, (SHORT)aptl[0].y, 

(SHORT)aptl[1].x, (SHORT)aptl[1].y, hwnd, HWND_T0P, 
pDlgItem->id, 0, 0 ); 

/* record first tabstop item - will receive default focus */ 
if (Ihctl && pDlgItem->flStyle & WS_TABSTOP) 
hctl = pahwnd[ i-1 ]; 

rclForm.xLeft * min( rclForm.xLeft, aptl[0].x ); 
rclForm.yBottom = min( rclForm.yBottom, aptl[0].y ); 
rclForm.xRight = max( rclForm.xRight, aptl[0].x+aptl[1].x ); 
rclForm.yTop = max( rclForm.yTop, aptl[0].y+aptl[1].y ); 

} 

WinSetWindowUShort( hwnd, QWS_CXFORH, 

(USHORT)(rclForm.xRight-rclFora.xLeft+ 

2*B0RDER_SIZE) ); 

WinSetWindowUShort( hwnd, QWS_CYFORM, 

(USHORT)(rcl Fora.yTop-rclFora.yBottom+ 

2*B0RDER_SIZE) ); 

WinSubclassWindow( hwndFrame, wpForaFrame );/* for scrollbars */ 
WinSubclassWindow( hwnd, pfnwp/*user defined window proc*/ ); 

set_scrollbars( hwnd, cxClient, cyClient ); 

if (!WinSendMsg( hwnd, WM_INITDLG, hctl, p )) 

WinSetFocus( HWND_DESKTOP, hctl ); 

if (pDlgItem->flStyle & WS_VISIBLE) 

WinShowWindow( hwndFrame, TRUE ); 

return hwnd; 


static MRESULT EXPENTRY wpForaFrame( HWND hwnd, USHORT msg, 

MPARAM mpl, MPARAM mp2 ) 

{ 

USHORT usPos, usMin, usMax; 

SHORT sMove; 

HWND hctl; 

MRESULT mr; 

RECTL rclUpdate; 

switch( msg ) 

{ 

case WM_HSCROLL: 
case WM_VSCROLL: 

hctl = WinWindowFromID( hwnd, SHORTlFROMMP(mpl) ); 
mr = WinSendMsg( hctl, SBM_QUERYRANGE, OL, OL ); 
usMin = SH0RT1FR0MMR( mr ); 
usMax = SH0RT2FR0MMR( mr ); 

usPos = SHORT1FROMMR( WinSendMsg( hctl, SBM_QUERYPOS, OL, OL ) ); 
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Listing 2 - Cont’d 

#if [defined(min) 

fdefine max(a,b) (((a) > (b)) ? (a) : (b)) 

Idefine min(a,b) (((a) < (b)) ? (a) : (b)) 

lendif 

switch (SH0RT2FR0MMP(mp2)) 

{ 

case SB_LINELEFT: /* #defined same as SB_LINEUP */ 
sMove = -min( LINE_SIZE, usPos-usMin ); 
break; 

case SBPAGELEFT: /* #defined same as SB_PAGEUP */ 
sMove = -min( 8*LINE_SIZE, usPos-usMin ); 
break; 

case $B_LINERIGHT:/* Idefined same as SB_LINEDOWN */ 
sMove = +min( LINE_SIZE, usMax-usPos ); 
break; 

case SB_PAGERIGHT:/* Idefined same as SB_PAGEDOWN */ 
sMove « +min( 8*LINE SIZE, usMax-usPos ); 
break; 

case SB_SLIDERPOSITION: 

sMove = SH0RT1FROMMP(mp2) - usPos; 
break; 
default: 

return OL; /* Spurious commands occur under CodeView */ 

1 

/* scroll the controls in the opposite direction to the scrollbar 
*/ 

if (SH0RT1FROMMP(mpl)==FID_HORZSCROLL) 

WinScrol1 Window( WinWindowFromID( hwnd, FID_CLIENT ), 

-sMove, 0, NULL, NULL, NULL, &rclUpdate, 
SW_SCROLLCHILDREN | SW_INVALIDATERGN ); 

else 

WinScrollWindow( WinWindowFromID( hwnd, FID_CLIENT ), 

0, +sMove, NULL, NULL, NULL, ArclUpdate, 
SWJCROLLCHILDREN ( SW_INVALIOATERGN ); 

WinSendMsg( hctl, SBM_SETPOS, MPFR0MSH0RT( usPos+sMove ), OL ); 
return OL; 

) 

return WinDefDlgProc( hwnd, msg, mpl, mp2 ); 


static void set_scrollbars( HWND hwnd, 

SHORT cxClient, SHORT cyClient ); 

/* internal routine to interpret tabs and cursor keys in the form */ 
static void FormNavigate( HWND hwnd, USHORT usVKey ); 

/* Default window procedure for a form window */ 

MRESULT EXPENTRY wpForm( HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2 ) 

( 

HPS hps; 

RECTL rcl; 

switch( msg ) 

f 

/* provides default action: no focus set */ 
case WMJNITDLG: return FALSE; 

case WM_CALCVALIDRECTS: 

/* keep child control windows in the top left of the form 
if and when it is resized */ 
return MRFROMSHORT( CVR_ALIGNTOP | CVR_ALIGNLEFT ); 

case WM_CHAR: 

{ 

USHORT usFlags = SHORTlFROMMP(mpl); 

if ( usFlags & KC_VIRTUALKEY && !(usFlags & KC_KEYUP) ) 
FormNavigate( hwnd, SH0RT2FR0MMP(mp2) ); 
break; 

) 

case WM_COMMAND: 

return OL; /* unlike WinDefDlgProc() does not dismiss window */ 

case WM_ERASEBACKGROUND: 

return MRFROMSHORT(TRUE); 


template from the given module and 
passes the template address on, with 
the rest of its parameters, to Form- 
Create() . Note that FormCreate() 
takes two more parameters than Uin- 
CreateDlgf). You can provide other 
resources, such as a menu, accelerator 
table or icon, much as you would for 
WinCreateStdWindowO, by setting the 
appropriate FCF_ flags in the dialog 
template. To comply with CUA, Form- 
Create() always supplies a titlebar, sys¬ 
tem menu, size border, and horizontal 
and vertical scrollbars, whether you ask 
for them or not. 

Dialog Templates 

PM stores dialog templates in 
memory as a header structure, 
DLGTEMPLATE, followed by an array of 
DLGTITEM structures, one for each con¬ 
trol, followed by the frame control flags, 
and the window class and window text 
names referenced by the DLGTITEM 
structures. PM usually stores the 
template in its own memory segment 
and discards it once the dialog is built. 

Figure 1 shows the structures in¬ 
volved. Note the first DLGTITEM structure 
contains information about the size and 
position of the dialog itself. Figure 2 is 
an annotated CodeView memory dump, 
showing a sample template resource. 
Periods mark field boundaries, colons 
mark record boundaries, and angle 
brackets enclose offsets to other 
records. The script used to generate the 
template is in Listing 3. 

As FormCreate() deciphers the 
template and creates a form, it also 
creates an array of control handles. 
FormCreate() stores this array in the 
client's window words for later use by 
FormEnumltemO . This is probably what 
UinCreateDlgO does as well, but this is 
not publicly documented. After building 
the form, FormCreate() installs message 
handlers for the frame and client, and 
sends a WM_INITDLG to the user-sup- 
plied client handler to let it initialize the 
form and, optionally, set the focus. 

Sizing And Scrolling 

The frame window procedure hand¬ 
les scrolling by calibrating the scroll bars 
when the window is resized and 
responding to messages from the 
horizontal and vertical scroll bars. The 
code calculates the form's size by 
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case WM_FOCUSCHANGE: 

/* control within form about to be given focus? */ 
if (!SHORT1FROMMP(mp2) 

&& WinQueryWindow( mpl, QW_PARENT, FALSE )==hwnd) 

{ 

SHORT x=0, y=0; 

SWP swp, swpCtl; 

RECTL rclUpdate; 

USHORT usPos; 

HWND hctl; 

HMND hwndFrame = WinQueryWindow( hwnd, QW_PARENT, FALSE ); 

WinQueryWindowPos( mpl, AswpCtl ); 

WinQueryWindowPos( hwnd, &swp ); 


if ( swpCtl .x < BORDER_SIZE ) 

X = BORDER_SIZE - swpCtl.x; 

el se 

if ( swpCtl.x + swpCtl.cx > swp.cx - BORDER_SIZE ) 
x = swp.cx - BORDER_SIZE - swpCtl.x - swpCtl.cx; 


if ( swpCtl.y < BORDER_SIZE ) 
y = BORDER_SIZE - swpCtl.y; 

else 

if ( swpCtl.y + swpCtl.cy > swp.cy - BORDER_$IZE ) 
y = swp.cy - BORDER_SIZE - swpCtl.y - swpCtl.cy; 

if (x | | y) 

WinScrollWindow( hwnd, x, y, NULL, NULL, NULL, 

irclUpdate, SW_SCROLLCHILDREN | SW_INVAUDATERGN ); 

if (x) 

{ 

hctl = WinWindowFromIO( hwndFrame, FID_HORZSCROLL ); 
usPos = SHORT1FROMMR( 

WinSendHsg( hctl, SBM_QUERYPOS, OL, OL ) ); 
WinSendMsg( hctl, SBM_SETPOS, 

MPFROMSHORT( usPos-x ), OL ); 


if 

( 


} 


(y) 

hctl = WinWindowFromID( hwndFrame, FID_VERTSCROLL ); 
usPos = SHORTlFROMMR( 

WinSendMsg( hctl, SBM_QUERYPOS, OL, OL ) ); 
WinSendMsg( hctl, SBM_SETPOS, 

MPFROMSHORT( usPos+y ), OL ); 


/* Check the moved control fits in the form window. 

If not, expand the form window. 

*/ 

WinQueryWindowPos( mpl, &swpCtl ); /* Find new location */ 

x * max( 0, swpCtl.x + swpCtl.cx - swp.cx + BORDER_SIZE ); 
y = max( 0, swpCtl.y + swpCtl.cy - swp.cy + BORDER_SIZE ); 

if (x || y) 

( 

SWP swp; 

WinQueryWindowPos( hwndFrame, &swp ); 
swp.cx +» x; 
swp.cy += y; 

WinSetWindowPos( hwndFrame, NULL, 0, 0, 

swp.cx, swp.cy, SWP_SIZE ); 

) 

} 

break; /* leave for WinDefDlgProc() */ 
case WM_PAINT: 

hps = WinBeginPaint( hwnd, NULL, NULL ); 

WinQueryWindowRect( hwnd, &rcl ); 

WinFi11Rect( hps, &rcl, SYSCLR_WINDOW ); 

WinEndPaint( hps ); 
return 0; 

case WM_SIZE: 

if (WinQueryWindowPtr( hwnd, QWL_USER+sizeof(PVOID) )) 

set_scrollbars( hwnd, SHORTlFROMMP(mp2), SH0RT2FR0MMP(mp2) ); 
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Listing 2 - Cont’d 

return 0; 
case WM_DESTR0Y: 

free( WinQueryWindowPtr( hwnd, QWL_USER+sizeof(PVOID) ) ); 
break; 

} 

return WinDefWindowProc( hwnd, msg, mpl, mp2 ); 


/* Update the scroll bars ranges so user will be able to scroll 
to parts of the form that will be outside the client area. 


The scroll bar range has two components: 
the number of pels between the left of the form and the 
left of the window, and the number of pels between the right 
of the window and the right of the form. 

*/ 

static void set_scrollbars( HWND hwnd, SHORT cxClient, SHORT cyClient ) 

{ 

SHORT cxForm, cyForm; 

SHORT sPos, sPosNew, sRange; 

RECTL rclUpdate; 

HWND hwndFrame = WinQueryWindow( hwnd, QW_PARENT, FALSE ); 

HWND hctl = WinWindowFromID( hwndFrame, FID_H0RZSCR0LL ); 

cxForm = WinQueryWindowUShort( hwnd, QWS_CXFORM ); 
cyForm * WinQueryWindowUShort( hwnd, QWS_CYFORM ); 

sPos = SH0RT1FR0MMR( WinSendMsg( hctl, SBM_QUERYPOS, OL, OL ) ); 

/* If the right of the window is beyond the right of the form 
scroll to the left if possible. 

*/ 

if (sPos && sPos + cxClient > cxForm) 

{ 

sPosNew = max( 0, cxForm - cxClient ); 

WinScrollWindow( hwnd, sPos-sPosNew, 0, 

NULL, NULL, NULL, irclUpdate, 

SW_SCROLLCHILDREN ); 

WinInvalidateRegion( hwnd, NULL, TRUE ); 
sPos = sPosNew; 

WinSendMsg( hctl, SBM_SETPOS, MPFROMSHORT( sPos ), OL ); 

) 

sRange = sPos + max( cxForm - cxClient - sPos, 0 ); 


if (sRange) 
( 


) 


WinEnableWindow( hctl, TRUE ); 

WinSendMsg( hctl, SBM_SETSCROLLBAR, MPFROMSHORT( sPos ), 
MPFR0M2SH0RT( 0, sRange ) ); 


el se 


WinEnableWindow( hctl, FALSE ); 


hctl = WinWindowFromID( hwndFrame, FID_VERTSCROLL ); 

sPos = SH0RT1FR0MMR( WinSendMsg( hctl, SBM_QUERYPOS, OL, OL ) ); 

if (sPos && sPos + cyClient > cyForm) 

{ 

sPosNew = max( 0, cyForm - cyClient ); 

WinScrol1Window( hwnd, 0, sPosNew-sPos, 

NULL, NULL, NULL, &rclUpdate, 
SW_SCROLLCHILDREN ); 

WinInvalidateRegion( hwnd, NULL, TRUE ); 
sPos = sPosNew; 

WinSendMsg( hctl, SBM SETPOS, MPFROMSHORT( sPos ), OL ); 

) 

sRange ■ sPos + max( cyForm - cyClient - sPos, 0 ); 
if (sRange) 

1 

WinEnableWindow( hctl, TRUE ); 

WinSendMsgf hctl, SBM SETSCROLLBAR, MPFROMSHORT{ sPos ), 
MPFR0M2SH0RT( 0, sRange ) ); 

} 

el se 

WinEnableWindowf hctl, FALSE ); 
return; 


Idefine STYLE( hwnd ) WinQueryWindowULong( hwnd, QWL STYLE ) 


querying all the controls to find their 
location and adding a margin around 
their maximum extent. 

Using The Default Form 
Procedure 

You should use wpFormf) as the 
default message handler for the window 
procedure for a form, instead of UinDef- 
DlgProc(), which is used for dialogs. 
wpForm() handles the tab and cursor 
keys by calling FormEnumltemf), and 
repaints the client area on request. It 
also tracks the cursor by automatically 
scrolling the form to keep the current 
control with focus fully visible within 
the window. Unlike UinDefDlgProcf), it 
does not dismiss the window if the user 
fails to process a command. 

Conclusion 

The demonstration program is in List¬ 
ing 4. The resource script for the demo 
is in Listing 5, while Listing 6 contains a 
Microsoft makefile that builds the 
demonstration program. 

PM and Windows do not directly 
support all the high-level interfaces 
described in the CUA guidelines. If your 
application uses dialog boxes for general 
data entry, it does not conform to the 
CUA specification. The module in Listing 
2 demonstrates how to create data 
entry windows that are CUA-compliant 
without giving up the advantages of 
dialog boxes. □ 
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static void FormNavigate( HWND hwnd, USHORT usVKey ) 

( 

HWND hctl = WinQueryFocus( HWND_DESKTOP, FALSE ); 

switch( usVKey ) 

{ 

case VK_TAB: 
do 

hctl = FormEnumItem( hwnd. hctl, EDIJOTTABITEM, FALSE ); 
while (STYLE( hctl )& WSDISABLED); 
break; 

case VK_BACKTAB: 
do 

hctl - FormEnumItem( hwnd. hctl, EDI_PREVTABITEM, FALSE ); 
while (STYLE( hctl )& WSDISABLED); 
break; 

case VKRIGHT: case VK_D0WN; 
do 

hctl = FormEnumItem( hwnd, hctl, EDI_NEXTGROUPITEM, FALSE ); 
while (SHORTlFROMMR(WinSendMsg( hctl. WM_QUERYDLGCODE, 0, 0 )) 

& DLGCJTATIC 

|| STYLE( hctl )& WS_DISABLED); 

break; 

case VKLEFT: case VK_UP: 
do 

hctl = FormEnumItem( hwnd, hctl, EDI_PREVGROUPITEH, FALSE ); 
while (SHORTlFROMMR(WinSendMsg( hctl, WM QUERYDLGCODE, 0, 0 )) 

& DLGC STATIC 

|| STYLE( hctl )& WSDISABLED); 

break; 

default: return; 

) 

WinSetFocus( HWND_DESKTOP, hctl ); 
return; 


HWND EXPENTRY FormEnumItem( HWND hwndForm, HWND hwnd, 

USHORT code, BOOL fLock ) 

( 

HWND ‘pahwnd = (HWNO*)WinQueryWindowPtr( hwndForm, 

QWL USER+sizeof(PVOID) ); 

HWND *phwnd; 

if (code != EDI_FIRSTTABITEM && code != EDI LASTTABITEM) 

( 

for (phwnd = pahwnd; *phwnd && ‘phwnd 1= hwnd; phwnd++){) 
if (!*phwnd) 
return NULL; 

) 

switch( code ) 

( 

case EDI_FIRSTTABITEM: 
for (phwnd=pahwnd; 

*phwnd && !(STYLE( *phwnd )& WS_TABSTOP); 
phwnd++)(( 
break; 

case EDI_LASTTABITEM: 

for Xphwnd=pahwnd; ‘phwnd; phwnd++)() 

while (-phwnd != pahwnd && ! (STYLE) ‘phwnd )& WS_TABSTOP)) 

{ /* do nothing */ ) 
break; 

case EDI_FIRSTGROUPITEM: 

while (!(STYLE( ‘phwnd )& WS_GR0UP) AS --phwnd ! = pahwnd){} 
break; 

case EDI LASTGROUPITEM: 

while (*++phwnd && !(STYLE( ‘phwnd )& WSGROUP)){) 

phwnd--; 

break; 

case EDI_NEXTTABITEM: 
do if (!*++phwnd) 
phwnd = pahwnd; 

while (!(STYLE( ‘phwnd )& WS_TABSTOP)); 
break; 
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case EDI_PREVTABITEM: 
do if (phwnd==pahwnd) 
while (*++phwnd){) 

while (!(STYLE( *—phwnd )& WS_TABSTOP)); 
break; 

case EDI NEXTGROUPITEM: 

if (T*++phwnd II STYLE( *phwnd )& WS_GR0UP) 
return FormEnumItem( hwndForm, *--phwnd, 

EDI_FIRSTGROUPITEH, fLock ); 

break; 

case EDI PREVGROUPITEM: 

if (phwnd==pahwnd || STYLE( ‘phwnd )& WS_GR0UP) 
return FormEnumItem( hwndForm, *phwnd, 

EDI_LASTGROUPITEM, fLock ); 

phwnd--; 

break; 

) 

if (fLock) 

WinLockWindow{ *phwnd, fLock ); 
return ‘phwnd; 


/* Utility routine to fetch the latest PM error and 
display it in a message box 

*/ 

void EXPENTRY ErrorInfoMessageBox( HAB hab, HWND hwnd, PSZ pszTitle ) 

( 

PERRINFO perrinfo » WinGetErrorlnfof hab ); 
if (perrinfo) 

{ 

SEL sel = SELECT0R0F( perrinfo ); 

PUSHORT aoffszMsg - MAKEP( sel, perrinfo->offaoffszMsg ); 

WinAlarm( HWND_DESKTOP, WA_ERROR ); 

WinMessageBox( HWND_DESKTOP, hwnd, 

MAKEP( sel, aoffszMsg[ 0 ] ), 
pszTitle, 0, 

MB_0K | MB_ICONEXCLAMATION | MB_MOVEABLE ); 
WinFreeErrorlnfof perrinfo ); 

) 

return; 

) 

/‘END*/ 




Figure 1 


typedef struct 

DLGTEMPLATE { 

/* 

dlgt */ 


USHORT 

cbTemplate; 

/* 

total length of template */ 

USHORT 

type; 

/* 

currently unused by PM */ 


USHORT 

codepage; 




USHORT 

offadlgti; 

/* 

offset of adlgti (OxE) */ 


USHORT 

fsTemplateStatus; 

/* 

unused - must be 1 */ 


USHORT 

iItemFocus; 

/* 

default 1st.focus item */ 


USHORT 

coffPresParams; 

/* 

unused - must be zero */ 


DLGTITEM 

adlgti [] ; } DLGTEMPLATE; 



typedef struct 

DLGTITEM { 

/* 

dlgti */ 


USHORT 

fsItemStatus; 

/* 

unused - must be zero */ 


USHORT 

cChildren; 




USHORT 

cchClassName; 

/* 

zero for standard controls 

*/ 

USHORT 

offClassName; 

/* 

just id for standard class 

*/ 

USHORT 

cchText; 




USHORT 

offText; 




ULONG 

flStyle; 




SHORT 

x; 




SHORT 

y; 




SHORT 

cx; 




SHORT 

cy; 




USHORT 

id; 




USHORT 

offPresParams; 

/* 

reserved */ 


USHORT 

offCtlData; 




} DLGTITEM; 






Notice to TS 
Subscribers 


Occasionally, TECH Specialist 
makes its mailing list available to 
vendors of products we think our 
readers will find interesting. Cur¬ 
rent subscribers receive free in¬ 
formation in the mail from these 
vendors. 

If you prefer that your name 
not be used in these mailings, 
please let us know. Just copy or 
clip this form and send it with 
your name and address to: 


TECH 

I. 






TECH Specialist 
2601 Iowa 

Lawrence, KS 66046 
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Listing 3 ( template ) 

Idefine IDC_OK 1 

Idefine IDC_CANCEL 2 

Idefine IOC_LISTBOX 3 

Idefine IDD DIALOG OxDDDD 


DLGTEMPLATE IDD_DIALOG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "A tall, wide list box", IDD_DIALOG, 7, 0x28, Oxl9D, 0x9B, 

FS_NOBYTEALIGN | FS_DLGBORDER j WS_VISIBLE | WS_CLIPSIBLINGS | 
WS_SAVEB ITS/*Ox94000090*/, FCF_SYSMENU | FCF_TITLEBAR/*Ox00000003*/ 

BEGIN 

CONTROL IDC_LISTBOX, 4, 0x14, 0x196, 0x82, "NewListBox", 

LS_OWNERDRAW | WS_VISIBLE/*Ox80000002*/ 

CONTROL "OK", IDC_OK, 4, 2, 0x18, OxOE, WC_BUTT0N/*3*/, BS_PUSHBUTTON | 
BS_DEFAULT | WS_GROUP | WS_TABSTOP | WS_VISIBLE/*80030400*/ 

CONTROL "Cancel", IDC_CANCEL, 0x21, 2, 0x27, OxOE, WC_BUTTON, BS_PUSHBUTTON | 
WS_TABSTOP | WS_VISIBLE/*80020000*/ 

END 


Script to Generate Template 


Listing 6 ( makefile ) 

#i 

I written for Microsoft C v.6.0 with nmake 

## 

CC=\c600\binp\cl -Alfu -G2s -Od -W4 -Zip 
INCLUDE=\c600\include 
OBJS=demo.obj form.obj 

demo.exe: $(OBJS) demo.res 
link $(OBJS),$@,,\c600\lib\os2.1ib/Co; 
rc $*.res $@ 

demo.obj: demo.c form.h 

form.obj: form.c form.h 

.rc.res: 
rc -r $*.rc 


Makefile for PM Forms Demo 



TCP/IP tor Windows 3 

Release 2.0 Now Shipping 

Software Development Kit and Applications* 

NEWT is the first TCP/IP package developed specifically (not 
converted from DOS) for Windows 3.0. NEWT-SDK takes full 
advantage of Windows' flexibility and multitasking capability. 
This software development kit offers the programmer direct 
access to the Transport, Network, and Datalink (MAC) layers. 


□ Implemented as a DLL (no TSR) 

□ Multiple windows run multiple 
TCP/IP sessions concurrently 

□ TCP, UDP, ICMP, IP, and MAC 

□ Ethernet, Token Ring and FDDI 

□ Berkeley 4.3BSD socket interface 

□ NDIS interface 

□ Concurrent LAN and SLIP 

□ Windows based set-up program 

□ Tracks and displays all network 
statistics 

□ Supports multiple network 
boards simultaneously 

□ Supports IP routing 

Only $500 


□ Three DLLs included: 
NEWT: TCP/IP stack 
FTP: file transfer 
SMTP: mail transfer 

□ Integrated SLIP dialing 

Applications* 

TELNET (VT100) 

FTP BIND 

TFTP Statistics 

SMTP Custom 

Mafi PING 

□ Point and click UT 

□ Context sensitive help 

□ Both client and server 
* Optional 


The first TCP/IP implemented as a Windows DLL 

NeXManage Inc. (408) 257-6404 


10020 N. DeAnza Blvd. #101, Cupertino, CA 95014 Fax: (408) 257 6405. 
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Universal 





Cl ATP Printer 

OLMI C Driver 


Listing 4 idemo.c) 



Idefine INCL_WIN 
linclude <os2.h> 

NEW! Text & Graphics! 


linclude “form.h" 

By including SLATE, you can 
print both Text and Graphics 


HAB hab; /* global accessed during forms auto-initialization */ 

on over 400 printers. 

Immediately! Painlessly! 


mainf) 

f 

You can use SLATE in your 


HAB _hab • hab = Winlnitialize( 0 ); 

HMQ hmsgq = WinCreateMsgQueue( hab, DEFAULT QUEUE SIZE ); 

product with no royalties. 


QMSG qmsg; 

Make your product more 
functional and competitive by 

taking advantage of SLATE’S 

advanced text features: 


if (FormLoad( HWND_DESKT0P, HWND_DESKT0P, wpForm, 0, 1, 0L )) 
while(WinGetMsg( _hab, &qmsg, 0L, 0, 0 )) 

WinDispatchMsg( _hab, &qmsg ); 

return 0; 

} 

/*end*/ 

• Support multiple printers on the same 


system. 


• Output to parallel printers, serial 



printers, DOS files, console, DOS 
print spooler, and Novell network 
printers. 


Program to Test Forms Module 


Listing 5 ( demo.rc) 

• Support proportional fonts laser 


printer soft fonts. 


• Set exact print positions. 


linclude <os2.h> 

You can add the NEW Graphics 


DLGTEMPLATE 1 L0AD0NCALL MOVEABLE DISCARDABLE 

Subsystem for advanced 


{ 

DIALOG "Address book", 100, 179, 114, 210, 90, 

graphics features: 


FS N0BYTEALIGN | FS SIZEBORDER | WS VISIBLE j WS CLIPSIBLINGS | 

• Print images from the screen, graphic 


WS SAVEBITS, FCF TITLEBAR | FCF SIZEBORDER | 

files, or custom image systems. 


FCF_MENU | FCF_MINMAX 

• Scale and Rotate the printed image. 


( 

CONTROL "Name", -1, 4, 76, 26, 8, WC STATIC, SS TEXT | 

• Convert colors to patterns. 


DT LEFT | DT TOP j WS GROUP | WS VISIBLE 

• Print grey scale (shaded) and color 


CONTROL "Street", -1, 4, 62, 30, 8, WC STATIC, SS TEXT | 

images. 


DT LEFT | 0T TOP | WS GROUP | WS VISIBLE 

CONTROL "City", -1, 4, 48, 20, 8, WC STATIC, SS TEXT | 

DT LEFT I DT TOP j WS GROUP | WS VISIBLE 

• Intermix text and graphics. 


CONTROL "Tel", -1, 4, 20, 38, 8, WC STATIC, SS TEXT | 

What is SLATE? 


DT LEFT | DT TOP | WS GROUP | WS VISIBLE 

CONTROL "State", -1, 4, 34, 22, 8, WC STATIC, SS TEXT | 

SLATE is a set of C libraries 
with over 150 text printing 


DT LEFT | DT TOP | WS GROUP | WS VISIBLE 

CONTROL "ZIP", -1, 90, 34, 18, 8, WC STATIC, SS TEXT | 

DT LEFT | DT TOP j WS GROUP | WS VISIBLE 

functions, a Database of over 


CONTROL "Fax", -1, 4, 6, 38, 8, WC STATIC, SS TEXT | 

400 printers, and tools for end 


DT LEFT | DT TOP | WS GROUP | WS VISIBLE 

user configuration and testing. 


CONTROL "Tech Specialist", 101, 44, 76, 158, 8, WC ENTRYFIELD, ES LEFT | 

ES MARGIN | WS TABST0P | WS VISIBLE 

SLATE with Graphics adds 


CONTROL "2601 Iowa Street.", 102, 44, 62, 158, 8, WC ENTRYFIELD, ES LEFT | 

ES MARGIN | WS TABST0P | WS VISIBLE 

over 60 graphic printing 


CONTROL "Lawrence", 103, 44, 48, 156, 8, WC ENTRYFIELD, ES LEFT | 

functions. 


ES MARGIN | WS TABST0P | WS VISIBLE 



CONTROL "KS", 104, 44, 34, 20, 8, WC ENTRYFIELD, ES LEFT | 

Call now for more information. 
Order SLATE for $299 or 

SLATE with Graphics for 


ES MARGIN | WS TABST0P | WS VISIBLE 

CONTROL ”66046", 105, 112, 34, 88, 8, WC ENTRYFIELD, ES LEFT | ES MARGIN | 

WS TABSTOP | WS VISIBLE 

CONTROL "(913)841-1631", 106, 44, 20, 92, 8, WC ENTRYFIELD, ES LEFT | 

$448 with our risk free, 30 day 


ES MARGIN | WS TABSTOP | WS VISIBLE 

return policy. 


CONTROL "(913)841-2624", 107, 44, 6, 92, 8, WC ENTRYFIELD, ES LEFT | 

ES MARGIN | WS TABSTOP | WS VISIBLE 

We accept Visa, Mastercard, COD's or 


) 

PO s from qualified companies. Source 
code, maintenance, and site licenses 
are available. Also ask for information 


) 

MENU 1 

about our S_PRINT Text Formatting 
System for Software Developers. 


{ 

MENUITEM "~File", -1 

MENUITEM “-Edit", -1 

800-346-3938 


MENUITEM “~View", -1 

) 

Xhe po Box 26195 


/*end*/ 

^rmmptrv Columbus, OH 43226 
OVIimitfU V 614-431-2667 

LtI'OUP FA x 614-431-5734 


Resource Script for PM Forms Demo 
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Enhancing 

QuickBASIC’s Capabilities 
With CALL INTERRUPT 

Phil Weber 


BASIC, it seems, is enjoying a renaissance. Since its creation at Dartmouth 
College over 25 years ago, programmers have criticized the language for its 
slowness and lack of structure. Today’s BASIC compilers, however, provide 
speed, structure and readability, while retaining the ease-of-use of their 
predecessors. One of the most powerful features of the new BASICS is their 
ability to call DOS and BIOS services directly. In Microsoft QuickBASIC, for ex¬ 
ample, this is done with the CALL INTERRUPT statement. This article examines 
CALL INTERRUPT in detail and explains why it is useful, how it works, and how 
you can put it to work in your programs. 

Who Needs It? 

Why would a BASIC program need to call DOS directly? After all, doesn’t 
BASIC provide file- and directory-handling commands of its own? While it is true 
that BASIC commands cover most DOS and BIOS services, some very practical 
operations are difficult or impossible to perform in BASIC alone. Say, for ex¬ 
ample, that you want to read the directory of a disk into an array. Believe it or 
not, the method recommended by Microsoft (because it is the only way to do 
so in pure BASIC) requires SHELLmg to DOS and redirecting the output of a DIR 
command to a file. Your program then reads and parses this file to get the 
directory information. It is kludges like this that give BASIC a bad reputation! As 
I will demonstrate, CALL INTERRUPT allows you to create a very fast and 
elegant directory routine without resorting to assembly language. In fact, DOS 
and the BIOS provide many services useful to a BASIC program: 

• Get a list of installed equipment: I/O ports, RAM, and so on. 

• Scroll a text window up or down on the screen. 

• Check the status of parallel and serial ports. 

• Get the name of the current drive or directory. 

• Return the full pathname of the currently running program. 
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What’s Going On In There? 

To get a feel for how CALL INTER¬ 
RUPT works, you should first understand 
how to call an interrupt in assembly 
language. First, you save any processor 
registers that need to be preserved. 
Next, you load the registers with the 
appropriate values for the interrupt 
desired. Finally, you issue an int in¬ 
struction, which causes program execu¬ 
tion to jump to the address pointed to 
by an interrupt vector, much as the 
BASIC CALL statement does. When the 
interrupt code executes an TRET state¬ 


ment, execution returns to the point 
immediately following the INT. 

CALL INTERRUPT is essentially a 
generic assembler routine that performs 
the above steps for you. You simply fill 
in the blanks by providing the correct 
register values in a variable of type 
RegType (see Listing 1), and CALL IN¬ 
TERRUPT preserves the starting register 
values, copies your values into the 
registers, and issues an INT instruction. 
When the interrupt returns, CALL IN¬ 
TERRUPT saves the final register values 


for your calling program, restores the 
original values, and exits. That is all 
there is to it! 

I should note at this point that CALL 
INTERRUPT is actually two routines: CALL 
INTERRUPT and CALL INTERRUPTX. The 
only difference between the two is that 
CALL INTERRUPTX allows you to change 
the segment registers, DS and ES, while 
CALL INTERRUPT does not. If the inter¬ 
rupt you are calling manipulates the 
segment registers, be sure you CALL 



Listing 1 

TYPE RegType 


ax 

AS 

INTEGER 

bx 

AS 

INTEGER 

cx 

AS 

INTEGER 

dx 

AS 

INTEGER 

bp 

AS 

INTEGER 

si 

AS 

INTEGER 

di 

AS 

INTEGER 

flags 

AS 

INTEGER 

END TYPE 



TYPE RegTypeX 


ax 

AS 

INTEGER 

bx 

AS 

INTEGER 

CX 

AS 

INTEGER 

dx 

AS 

INTEGER 

bp 

AS 

INTEGER 

si 

AS 

INTEGER 

di 

AS 

INTEGER 

flags 

AS 

INTEGER 

ds 

AS 

INTEGER 

es 

AS 

INTEGER 

END TYPE 



Call Interrupt Variable Definitions 




Table 1 


Service 

Func 

Registers In 

Registers Out 

Get DTA Address 

2Fh 

AH = 2Fh 

AX = Return Code 

ES:BX = Pointer to DTA 

Set DTA Address 

1Ah 

AH = 1Ah 

DS:DX = Pointer to file 
spec 

None 

start File Search 

4 Eh 

AH = 4 Eh 

CX = Search Attribute 
DS:DX = Pointer to file 
spec 

AX = Return Code 

Continue File Search 

4Fh 

AH = 4Fh 

DS:DX = Unchanged 
from call to 4E 

AX = Return Code 

Summary of DOS Services Used in Example Programs 


Table 2 


Start 

Length 

Description 

1 

21 

Area used by DOS for function 4Fh 

22 

1 

Attribute of file found 

23 

2 

Time stamp of file (encoded) 

25 

2 

Date stamp of file (encoded) 

27 

4 

File size in bytes (long integer) 

31 

13 

Filename and extension (null-terminated) 


Information Returned in DTA after a CALL to Function 4Eh 


Table 3 


Bit 

Value 

Meaning 

7 6 5 4 3 2 1 0 

.1 

1 

Read-Only 

.1 . 

2 

Hidden 

.1 . . 

4 

System 

. . . . 1 . . . 

8 

Volume Label 

. . . 1 . . . . 

16 

Subdirectory 

. . 1. 

32 

Arhive 

. 1. 

64 

Unused 

1. 

128 

Unused 

File Attribute Bit Coding 
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INTERRUPTX and pass it a variable of 
type RegTypeX. 

Using CALL INTERRUPT 

The CALL INTERRUPT routine is not 
built into the QuickBASIC language. In¬ 
stead, it resides in the assembler 
module INTRPT.OBJ which, in turn, 
resides in the libraries QB.LIB and 
QB.QLB on your QuickBASIC distribution 
disks. To use CALL INTERRUPT within 
the editing environment, tell QuickBASIC 
to load QB.QLB by starting the program 
with the /L switch: 


QB /L QB.QLB 


If you need to combine CALL INTERRUPT 
with a Quick Library you are already 
using, consult your QuickBASIC 
documentation. Before you can CALL it, 
your code must define the appropriate 
TYPE structure, either RegType or Reg¬ 
TypeX. You may enter the TYPE defini¬ 
tion directly in your source code, or you 
may prefer to simply $INCLUDE the file 
QB.BI (from your QuickBASIC distribution 
disks) at the top of your code. Finally, 
you'll need to know how to properly set 
up the registers for the interrupt(s) you 
want to use. There are many fine books 
that can help you with this-, my personal 
favorite is Peter Norton's Programmer’s 
Guide to the IBM PC. 

Table 1 lists the inputs and outputs 
of four useful DOS services. You access 
these services by calling interrupt 21h 
with the number of the desired function 
in the AH (the upper half of the AX) 
register. Functions 2Fh and lAh affect 
the DOS Disk Transfer Area (DTA.) The 
DTA is an area in memory where DOS 
stores information about files and direc¬ 
tories (see Table 2). While your BASIC 
program could simply PEEK into the 
default DTA, it is much more efficient to 
tell DOS (via function lAh) to use a BASIC 
string variable as its DTA. That way, your 
program can use BASIC’s string-handling 
functions, which are significantly faster 
than PEEK, to extract the data it needs. 
Before you change the DTA, though, it is 
a good idea to save its original address 
(returned by function 2Fh), so you can 
restore it when your program is finished. 

The other two functions in Table 1 
are the same ones DOS uses to search 
for files when you type DIR at the DOS 
prompt. Function 4Eh finds the first file 
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•fl grophics-MENU interface can contain 
windows, icons, menus, checked and 
scrolled lists of items, buttons, text edit 
uuindouu, data entry form menus 5t more. 

• CASE tools ore included to provide on 
on-screen UJYSIUUYG design 
environment for creating some menu 
types uuith complete automatic code 
generation for the target compiler. 
•Extensive flexibility is available to 
change colors, sizes, and format of most 
items. Library source is available to 
alloiu total control uuhen required. 

• Background tasking capability allows a 
graphics-MENU interface to be run with 
a real time application. 

yowl 

application aeut tov/i icYee tXti&: 


graphics-M€NU is o 
collection of 
libraries, CflS€ 
tools and utilities 
to enable the 
softuuare developer 
to quickly create a 
professional 
Graphical User 
Interface for any 
application. 


•Memory utilization is conserved by 
using TPU's for Pascal and many small 
.OBJ files for C. EMS can be 
automatically used to automatically 
save the underlying graphics image. 
(Automatic storage to disk is available 
with the Genus GX version). 

•Complete support for both mouse and 
keyboard. 

• UUorks with any font or video mode 
supported by the underlying graphics 
environment. 

• Choose native graphics variant to work 
standalone with your Borland or 
Microsoft compiler, or external graphics 
variant to work with MetaUJindow or 
Genus GX graphics. 




0% tfay. 


MicrosoftC 6.0 Genus GX 
BGI graphics graphics MetaUJindow 


• compilers 
•graphics 
environments 


Turbo C 
Turbo C++ 
Turbo Pascal 
Microsoft C 
JPI Topspeed 
Compilers 
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matching a given file specification and attribute (returning the 
file's directory information in the DTA), and function 4Fh con¬ 
tinues the search. When there are no more matching files in 
the specified directory, function 4Fh returns with AX = 18. 
Note that all four of these functions use the segment registers, 
DS and ES, so you will need to CALL INTERRUPTX when you 
use them. 

Testing File Existence 

The program in Listing 2 contains a simple function called 
Exist that checks for the existence of a file and returns -1 if 
the file is found or 0 if it is not. The procedure uses DOS func¬ 
tion 4Eh to search for the first occurrence of the file. The first 
step is to create a RegTypeX variable (I call mine Regs, but you 
may use any valid BASIC variable name). Next, you have to 
add a CHR$(0) to the end of the filename, since DOS looks for 
a null byte to mark the end of the string. I have created a 
temporary variable for this purpose, so that Exist returns the 
original FileSpec$ unchanged. Then you have to set up the 
registers for the CALL to interrupt 21h, function 4Eh. 

Table 1 refers to the AH register. If you have never done 
this before, you may be thinking, “I see the AX register in 
RegTypeX, but where is AHV Good question! Each general-pur¬ 
pose register (AX, BX, CX, and DX) is two bytes long. The in¬ 
dividual high and low bytes of each register are often used 
separately, and their names end with H (for high) and L (for 
low). So the AH register is simply the most significant byte of 
AX. You can put a value into the AH register as I have done, by 
specifying the entire 16-bit value of AX in hexadecimal form 
(&H4E00), or you may prefer to multiply the desired value by 
256, which shifts it into the high byte of AX. 

DOS function 4Eh expects the CX register to indicate the 
attributes to use when searching for files. Table 3 shows the 
meaning of the various bits in the attribute byte. If you specify 
any combination of the hidden, system, or directory bits, the 
search will find normal files and files matching those at¬ 
tributes. If you specify the volume label bit, only the volume 
label will be found. Functions 4Eh and 4Fh do not use the 
archive and read-only bits. The Exist function in Listing 2 sets 
CX to zero to search only for regular files, but by using dif¬ 
ferent values in CX, you could easily search for directory 
names or the disk volume label. The rest of the registers are 
straightforward. You set DS to the segment of the filename 
string (returned by the BASIC VARSEG function), and DX is the 
offset (returned by SADD.) 

Once you initialize the registers, it is time to CALL INTER¬ 
RUPTX. The interrupt routine searches the current directory (or 
the one specified in FileSpec$) for the desired file. If it finds 
no match, the lower byte of AX (that is AL, remember?) returns 
an error code and control passes back to your program. If it 
finds a matching file, DOS copies its directory information into 
the DTA, and AL returns with a value of 0. To extract the value 
of AL from the two-byte AX register, I use the logical AND 
operator. The expression "Regs.ax AND 255“ returns the 
value stored in the lower byte of AX. To obtain the value of 
AH, use “Regs.ax \ 256". Here, you do not really need the 
exact value of the return code; if it is not 0, you know the file 
was not there. 


So, there you have it - a useful DOS function call, without 
assembly language, and in only 12 lines of code! An 
equivalent BASIC routine would require you to OPEN the file for 
RANDOM and check to see if its length was zero, indicating that 
it had not existed before the OPEN statement created it. Then 
you would either have to delete the zero-length file and issue 
an error message, or possibly CLOSE and r e-OPEN the file in the 
desired mode. 

Directory Assistance 

The next example (Listing 3) is a bit more complex than the 
first, but not really more difficult. While Exist searches for the 
first file matching a given specification, GetDir searches for all 
matching files, and returns their names in a string array. 

The first thing to do if you plan to fill a string array with 
data is Table out how large an array you will need; that is the 
purpose of the FileCount function. It performs exactly the 
same steps as GetDir (discussed later), except that instead of 
copying the file names into an array, it simply increments a 
counter variable for each matching file. FileCount returns the 
number of files so that the calling program can DIM the array 
to the optimum number of elements. It may seem wasteful to 
perform the same steps twice, but DOS and BASIC buffer disk 
reads, so the disk is only accessed once or twice and the 
process is finished before you know it. 

Like Exist, FileCount begins its work by appending a 
zero byte to the file spec and CALLing interrupt 21h, function 
4Eh to find the first match, if the file is found, the procedure 
enters a loop, adding one to the value of the Count variable 
and CALL'mg function 4Fh (Find Next) until AX returns 18, in¬ 
dicating that no more matching files exist. Once the main pro¬ 
gram knows how many file names it is going to read, it can 
DIMe nsion a string array to hold them, and move on to the 
GetDir routine. 

As explained previously, the core of GetDir is identical to 
FileCount (in fact, I cut and pasted the code from one into 
the other). The main difference is that GetDir actually does 
something with the information DOS returns in the disk trans¬ 
fer area, so GetDir contains additional code to preserve, read 
and restore the DTA. First, GetDir CALLS DOS function 2Fh to 
get the address of the current DTA and saves it in the vari¬ 
ables OldDTASeg and OldDTAOfs. Then the code creates its 
own DTA (a 44-byte BASIC string variable) and tells DOS to use 
it via function lAh. Next come the familiar CALLS to functions 
4Eh and 4Fh, to read the file names from the disk directory. 
GetDir, however, extracts the name of each file from the DTA 
and saves it in the string array. As Table 2 indicates, the 
filename begins at byte 31 of the DTA and ends with a null 
byte. So the program line: 

Array$(Element) = MID$(DTA$, 31, 

INSTR(32, DTA$, CHR$(0)) - 31) 

pulls the file name out of DTA$ and stores it in one element of 
the string array. GetDir then increments the element number 
and the process continues until there are no more matching 
files. Finally, function lAh is CALLe d to restore the DTA to its 
original address, and control returns to the calling program. 

(text continued on page 24) 
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9:45. Buttons and hotwords establish links to other 
pages and documents. Even to other applications 
through DDE. 


10:15. OpenScript is a lull-featured OOP language 
with built-in syntax checker and debugger. 


10:58. Finished. An elegant solution quickly and 
easily. Next? 


Something for people 
who watch the clock. 


Software scheduling used to happen on a calendar. 

Now you can do it on a watch. 

Introducing ToolBook® 1.5. The software construction set that lets 
developers build Windows' programs faster than you can say C++. 

ToolBook’s graphical programming features enable you to quickly 
create prototypes. Instead of writing pages of complex code to create a 
screen, just draw the screen. Instead of time-consuming.exercises to 
change the screen, you simply click and drag. Instead of weekends at the 
office, spend them at home reading your favorite computer magazines. 

ToolBook includes OpenScript? An OOP language that has the 
muscle and agility you're looking for in a serious development tool. Plus 
a built-in syntax checker and debugger to find and fix problems faster. 

Is there a limit to how complex you can get with something that 
works this easily? Yes. We're just not sure what it is. Because if you can 
think of it, you can use ToolBook to create it. 

In fact, you can make it come alive.ToolBook’s Script Recorder 
creates animation sequences with a simple point and click. 

ToolBook offers other sophisticated graphical capabilities, too. You 
can take advantage of a whole range of colors, a clip-art library and 



graphics from other Windows applications. Even import 256-color 
bitmap images up to 1 megabyte in size. 

You can link ideas any way you want, too.ToolBook’s hypemavigation 
features let you make the connections. Once they’re made, you can go 
deeper and deeper into large volumes of information. Just by clicking 
a hotword or a button. 

You can extend OpenScript with Dynamic Link Libraries, which 
are created in other programming languages. So ToolBook is ideal for 
putting a graphical interface on your mission-critical applications. 

ToolBook also supports Dynamic Data Exchange, which allows you 
to build solutions by integrating multiple Windows applications. 

And just to get you up and running quicker,ToolBook comes with 
a suite of sample applications with all scripts intact. Incorporate 
them. Or take them apart. But you don't have to start from scratch. 

If you’re interested in learning more, call 1 (800) 624-8999, Ext. 299R 
and ask for a brochure and the name of your authorized dealer. For 
international inquiries, send a fax to (206) 454-0672 requesting inter¬ 
national information. 

Then prepare for a time change. 


TOOLBOOK \p<fsifrn=T*ix 

Software Construction Set For Windows 

llO-IIOUi Ave., N.E.. Suite 717. Bellevue. WA 98004 


Asymetrix. ToolBook and OpenScript are registered trademarks of Asymetrix Corporation. Windows is a trademark of Microsoft Corporation. Where indicated, 
product and company names are trademarks/registered trademarks of their respective holders. 
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C CODE FOR THE PC 

source code, of course 


NEW! Professional IDL (interface generator for complex data; multiple inheritance, ASCII and binary external forms, tools; includes book) .... $360 
MH—p (fast CH—|- math classes; indexing, matrices & vectors, numerics, memory handling, I/O; specify C+ + compiler/Tbrbo, Zortech, dock.) $395 

C++/Views (C++ interface to MS Windows 3.0; over 60 classes; free broswer (no source); no roya lties; Zortech C++ only) .$395 

ZIP Image Processor & Victor Image Library Version 2.0 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

TUrboTpX (Release 3.0; HP, PS, dot drivers; CM fonts; Lal+X; MetaFont).$250 

db-File & db.Retrieve Bundle by Raima (B-tree and network database with SQL query and report writer; multi-user $475).$245 

TE Editor Developer’s Kit for Windows (full screen editor, undo command, multiple windows; inc. TER for application build-in; no royalties) $220 

NE W! c.pslib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support.$170 

Report Right (report writer and graph generator for Windows 3.0).$170 

C-Index/PC Database Library (fast B+ tree indexing, string/binary/custom keys, multiple record formats/file, 170-page manual) .$165 

Rogue Wave tools.h++ or math.h++ Class Library (extensive docs).each $165 

WKS Library Version 2.01 (C program interface to Lotus 1-2-3, dBase, Supercalc 4, Quatro, & Clipper) .$155 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).each $150 

Delorie GCC for MS-DOS (Version 1.39; includes C++, assembler & DOS extender; complete source code and makefiles).$150 

NE W! CDB for Windows (database toolkit; ISAM, DDL, relational & network, space reuse, concurrent access; fast, manual, no royalty).$145 

Vmem/C (virtual memory manager; least-recently used pager; dynamic expansion of swap file) .$140 

TE Editor Developer’s Kit (full screen editor, undo command, multiple windows).$130 

C Communications Toolkit by Magna Carta (multi-port & co-processor board support, FAX, interrupt driven, emulations, xfer protocols) . . $125 

C++ Object Library (virtual windows, I/O, lists, file free space management, keyed ISAM file I/O).$125 

SilverWare ”C” EMM Library (60 interface functions to EMM Version 4.0) .$120 

WinMem (unlimited global memory handles for Windows 3.0, 4-byte overheadper block rather than 20, virtual memory for 286).$110 

Updated! PC/IP (CMU/MIT TCP/IP for PCs; Clarkson drivers, SOS & SOSS NFS clones, Bdale mailer, PCRoute & PCBridge, NDIS, ODI, Beholder) . $100 

NEW! Heapman (application memory management for Windows 3.0; 64K bytes of heap space; includes memoiy browser/debugger).$100 

NE W! SCM (portable Scheme in C, conforms to IEEE and 3.99 specs, garbage collection off C stack for easy mixing with C).$100 

NEW! CDB for DOS & Unix (database toolkit; ISAM, DDL, relational & network, space reuse, concurrent access; fast, no manual, no royalty) . . . $95 

PowerSTOR (Version 1.2; extended heap space on extended memory, expanded memory, and/or hard disk).$95 

MIRACL Multiprecision Integer & Rational Arithmetic C Library (nearly 100 functions; C & C++; from Ireland).$90 

Disassembler (8086/80286/80386/80C186 with 80287/80387/80C187 NPX).$90 

Booter Toolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$85 

VM4C (virtual memory manager for C; swaps blocks to disk; small, fast, simple) .$80 

VMEM (virtual memory manager by Blake McBride, Version 3.6, LRU pager, dynamic swap file, image save/restore).$80 

NEW! Mini IDL (interface generator for complex data; single inheritance, translator & table generator tools, ASCII external form; includes book) . $80 

BGI Printer Driver Toolkit (BGI drivers for Epson 9- & 24-pin, HP LaserJet II, & PaintJet printers).$75 

COMM-DRV (interrupt-driven serial communication, device drivers & serial port monitors; source for libraries only; complete source $200) . $75 

NEW! cbase (C database library, sequential & b+-tree random access, buffered block I/O, file-level locking) .$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or CH—h).each $65 

Foundations-1 C++ Class Library (ASCII record I/O, bit arrays, exception handling, B-tree, persistent objects).$60 

C-LIN (linear algebra library; 42 vector & matrix functions; matrix inversion & decomposition; system-of-equations solution).$60 

MultiStr (evaluates a string containing multiple ASCII arithmetic expressions with variables).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

FinanC (large collection of financial function including bond, inventory, stock portfolio, & cash flow).$55 

NE W! TILE Forth (32-bit Forth-83 in C; lots of extensions including multi-tasking & classes/instances;link in C routines; DOS & Unfit).$50 

Pascal P-Code Compiler & Interpreter or Pascal-to-C Translator (Level 0 ISO standard Pascal with some Level 1 features) .each $50 

CALC (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

Floppy TAR (TAR backup and restore on MS-DOS devices; direct access to non-standard devices) .$50 

C Compiler Pack (5 C compilers; 3 for 8086 (gcc, MicroC, Small C), 2 for 68000 (Sozobon, cc68); gcc ports include library source only) . . . $50 

GNUisli MS-DOS (ports of 17 GNU programs to MS-DOS organized by Thorsten Ohl).$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obj files to .asm files; output is MASM compatible) .$50 

CLIPS (rule-based expert system generator, Version 4.3; advanced manuals available at additional cost) .$50 

NIH Class Library & Book (basic CH—(- classes & Data Abstraction and Object-Oriented Programming in C+ + in softback by Keith Gorlen) . $50 

Upgrade! Editor Pack (fourteen public domain editors; inc. microEmacs 3.11, Stevie, Elvis, Moke, mg2a, DTE, Jove, & Origami).$50 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$45 

DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; domestic distribution only) .... $40 

RXC & EGREP Version 2.0 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Bison & BYACC (YACC workalike parser generators; documentation; no restrictions on use of BYACC output).$35 

PC-XINU (Comer’s XINU operating system for PC).$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

REGX Plus (search and replace string manipulation routines based on regular expressions).$30 

GNU Awk & Dill for PC (both programs in one package).$30 

Updated! Cmnch Pack (30 file compression & expansion programs).$30 

Updated! Make Pack (eight versions of Make including dmake 3.7, GNU Make, Cake, and Gymake and a makefile maker).$30 

NE W! GNU Ghostscript (Turbo C makefile, MS-DOS executable, Paintjet driver, all fonts).$25 

BigNum (portable and efficient arbitrary-precision arithmetic package; hardcopy docs; from France).$25 

String Pack (lots of string routines; CH—(- String class, BAWK, word wrap, fuzzy search, Boyer-Moore, Hypertext, etc.).$25 

NEW! UUPC Pack (UUCP for the PC; UUPC Version 1.10a by Wonderworks and smail/PC Version 2.5 by Stephen C. THer).$25 

PC-MAIL (UUCP mailer by Wietse Z. Venema; send, receive, and manage UUCP mail; from Holland) .$25 

NEW! Tel (Tool Command Language; add shell programming programming capability to any command line; elegant command line language) . . . $25 

PERL for MS-DOS (C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 2.3.6 with docs) .$25 

Using CH—|-Library (the code from the book by Bruce Eckel and then some; Zortech 2.0 compatible).$25 

Updated! XLISP 2.1 (includes Almy improvements).$20 

GNU Chess (GNU Version 3.1 & Windows Version 1.01; executable included; requires SDK to build; truly beautiful!).$20 

GNU RCS (FSF’s version of the Revision Control System; like Unix's SCCS only better; keeps track of software development).$20 

SDBM (fast, disk-based hash table manager for really large hash tables; clone of Unix ndbmj .$20 

Data 

NEW! Moby Thesaurus (25K root words, 1.2M synonyms; requires signed license agreement).$350 

Moby Part-of-Speech (200,000 words and phrases described by prioritized part(s)-of-speech).$120 

Moby Words (500,000 words & phrases, 9,000 stars, 15,000 names).$80 

NEW! Moby Shakespeare (plays, sonnets, etc. ... every last word).$60 

Dictionary Word List (234,932 words in alphabetical order) .$60 

NEW! Roget’s 1911 Thesaurus.$40 

U. S. Cities (names & longitude/latitude of 32,000 U.S. cities and 6,000 state boundary points).$35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

Linguistic Experiment Dictionary (73,476 offbeat words with status and part-of-speech) .$30 


The Austin Code Works Voice: (512) 258-0785 

11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 

Austin, Texas 78750-3587 USA E-mail: info@acw.com 

Free surface shipping for cash in advance For delivery in Texas add 7% MasterCard/VISA 
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Listing 2 {exist.bas) 


DEFINT A-Z 

1 $ INCLUDE: 'qb.bi 1 

DECLARE FUNCTION Exist (FileSpec$) 

INPUT “Enter desired file spec: ", FileSpecJ 
IF Exist(FileSpec$) THEN 

PRINT FileSpecJ + " exists." 

ELSE 

PRINT FileSpec$ + " not found." 

END IF 
END 

FUNCTION Exist (FileSpecJ) 

DIM Regs AS RegTypeX 
Temp$ = FileSpecJ + CHR$(0) 

Regs.ax ■ &H4E00 'Find first matching file 

Regs.cx = 0 

Regs.ds = VARSEG(TempJ) 

Regs.dx = SADD(Temp$) 

CALL InterruptX(&H21, Regs, Regs) 

IF Regs.ax AND 255 THEN 
Exist = 0 
ELSE 

Exist = -1 
END IF 

END FUNCTION 


Checks for Existence of File 


Listing 3 {dir.bas) 


DEFINT A-Z 
'{INCLUDE: 'qb.bi' 

DECLARE SUB GetDir (FileSpecJ, ArrayJO) 

DECLARE FUNCTION FileCount (FileSpecJ) 

CLS 

INPUT "Enter desired path & file spec: ", TempJ 
PRINT 

Elements = FileCount(TempJ) 

IF Elements THEN 

REDIM DirectoryJ(l TO Elements) 

CALL GetDir(TempJ, DirectoryJO) 

FOR I = 1 TO Elements 
PRINT DirectoryJ(I) 

NEXT 

ELSE 

PRINT "File spec not found." 

END IF 
END 


Reads Specified Directory into String Array 


THE FAST, FLEXIBLE 
EASY TO USE GUI 

TEGL WINDOWS TOOLKIT II 
The TEGL Windows Toolkit II is really 
three toolkits in one: a graphics inter¬ 
face, a memory manager and a window 
manager. Together they provide a pro¬ 
gramming environment. With the tools 
you get you can build a true event driven 
GUI for your DOS application. 


OUTSTANDING FEATURES 


You get all these features and 
more for only $99: 

* Adds as little as 100 K to the size of an 
application. 

* Virtual memory management using 
EMS hard disk and handles. 

* Extensive keyboard, mouse and timer 
event hooks. 

* An icon editor to design and edit your own 
icons. 

* World coordinates make it easier to fit 
data to the screen. 

* TEGL graphics interface, a virtual plug¬ 
in replacement for BGI, but much faster 
and with special routines for windowing. 

* 40+ bit mapped fonts, some fonts support 
the complete IBM character set. 

* Font editor to create fonts up to 100 x 100 
pixels. 

* Dialogue management for easy data 
entry, pick lists, and messaging. 

* Turbo Pascal objects and Turbo C++ 
class library. 

* CGA, Hercules, EGA ,VGA and SVGA 
support in 2, 16 and 256 colors. 

* Pascal version supports Turbo Pascal/ 
Quick Pascal. The C version supports 
Turbo C/C++, Quick C, Microsoft C and 
WATCOM C. 


WINDOW ROUTINES 


Fast scrolling in any direction, stan¬ 
dard character I/O, local menus, re- 
sizeable, scroll bars, headers, graphics 
clipping, CRT windows. 

The Complete Games Toolkit II 
Includes the TEGL Windows Toolkit plus com¬ 
plete source code for five games. The games are 
great examples of the use of the toolkit. Even in¬ 
cludes an electronic deck of cards to create your 
own card games. 


EXTRA BENEFITS 


No Royalties - Source Code Included 
30-day Money Back Guarantee 

“Order today”.(604)669-2577*"* 

Fax (604)688-9530 

Visa/Mastercard/Cheque/Money Order 
TEGL Windows Toolkit II Release 2.0 
Pascal $99 C $99 

Complete Games Toolkit $139 
Shipping & Handling $10 
Shipping outside Canada & U.S.A. $15 
Canadian residents add 7% GST 

TEGL SYSTEMS CORPORATION 
780-789 West Pender Street, Vancouver 
British Columbia, Canada V6C 1H2 
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Listing 3 

- Cont’d 

FUNCTION FileCount (FileSpec$) 


DIM Regs AS RegTypeX 


Temp$ = FileSpeci + CHR$(0) 

Regs.ax = &H4E00 

Regs.cx = 0 

Regs.ds = VARSEG(Tempi) 

Regs.dx = SADD(Temp$) 

CALL InterruptX(&H21, Regs, Regs) 

'Find first matching file 

Count = 0 

IF Regs.Flags AND 1 THEN 

EXIT FUNCTION 

END IF 

'File not found 

DO 

Count = Count + 1 

Regs.ax = &H4F00 

CALL InterruptX(&H21, Regs, Regs) 

IF Regs.ax = 18 THEN EXIT DO 

LOOP 

'Find next until there 
'ain't no more 

FileCount = Count 

'Return number of files found 

END FUNCTION 


SUB GetDir (FileSpeci, ArrayiO) 


DIM Regs AS RegTypeX 


Regs.ax = &H2F00 

CALL InterruptX(&H21, Regs, Regs) 
OldDTASeg = Regs.es 

OldDTAOfs = Regs.bx 

'Get DTA 

'Save original address 
'so we can restore it later. 

DTA$ = STRINGS(45, 0) 

Regs.ax = SH1A00 

Regs.ds = VARSEG(DTA$) 

Regs.dx = SADD(DTA$) 

CALL InterruptX(&H21, Regs, Regs) 

'Initialize a DTA 
'Set new DTA 

Tempi = FileSpect + CHRi(O) 

Regs, ax = 8.H4E00 

Regs.cx = 0 

Regs.ds = VARSEG(Tempi) 

Regs.dx = SADD(Tempi) 

CALL InterruptX(&H21, Regs, Regs) 

'Find first matching file 

IF (Regs.Flags AND 1) THEN 'Error 

EXIT SUB 

ELSE 

Element = LBOUND(Arrayi) 

Arrayi(Element) = MIDi(DTAi, 31, INSTR(32, DTA$, CHR$(0)) - 31) 

END IF 

DO 

Element * Element + 1 

Regs.ax = &H4F00 'Find next until there 

CALL InterruptX(&H21, Regs, Regs) 'ain't no more 

IF Regs.ax = 18 THEN EXIT DO 

IF Element <= UBOUND(Arrayi) THEN 

Arrayi(Element) = MIDi(DTAi, 31, INSTR(32, DTAt, CHRi(O)) - 31) 

END IF 

LOOP 

Regs.ax = &H1A00 

Regs.ds = OldDTASeg 

Regs.dx = OldDTAOfs 

CALL lnterruptX(&H21, Regs, Regs) 

'Restore original DTA 

END SUB 



Not Just For Beginners 
Anymore 

I hope the above discussion has 
given you some insight into the power 
of CALL INTERRUPT and the new 
generation of BASIC compilers that use 
it. With a little ingenuity, you can now 
write BASIC programs that are as fast 
and efficient as those in any other high- 
level language, without giving up the in¬ 
tuitiveness and readability we've come 
to expect from BASIC. If you have com¬ 
ments or ideas on BASIC programming, 
I’d like to hear from you. I can be 
reached at CompuServe ID number 
72451,3401. Happy programming! □ 
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TEGL: High Performance Windows In A Low-Cost Package 


Comments By Victor R. Volkman 


Introduction 

The TEGL Windows Toolkit II by TEGL Systems Corporation 
(Vancouver, B.C.) is a graphics interface, window manager, and 
memory manager for developing standalone graphics applica¬ 
tions on MS-DOS. TEGL Windows Toolkit II v2.0 is available for a 
variety of C and Pascal language systems. The toolkit contains 
the full source code and make files necessary to rebuild the 
entire product. TEGL Windows supports most popular graphics 
adapters, including SuperVGA cards. Applications built with 
TEGL Windows may be distributed free of charge as long as 
they include a copyright notice. At $99, the TEGL toolkit costs 


TEGL 

TEGL Systems Corporation 

Suite 780-789 West Pender Street 

Vancouver, BC CANADA V6C 1H2 

Phone: (604) 669-2577 Fax: (604) 668-9530 

E-mail: CompuServe 74370,2354 (c/o Richard Tom) 

TEGL BBS: (604) 681-8769 


far less for the same functionality that many other popular 
GUIs provide. 

I received The TEGL Windows Toolkit on a single 3 1/2 inch 
1.44M diskette. TEGL Systems Corp. will ship the toolkit on any 
density 3 1/2 inch or 5 1/4 inch size diskette you specify. 
Nearly all of the files on the diskette were compressed in the 
PkZIP file format. The entire uncompressed toolkit requires 
about 5Mb of disk space. The TEGL Windows Toolkit for C is 
designed to work with Borland Turbo C v2.0 and Turbo C++ 
vl. 0-2.0, Microsoft C v5. 1-6.0 and Quick C V2.0-2.5, WATCOM C 
v8.0, and JPI C/C++. Support for each of these compilers is in¬ 
cluded in the same base package. TEGL Windows for Pascal is 
designed to work with Borland Turbo Pascal V5.0-6.0 and 
Microsoft Quick Pascal vl.0. TEGL works exclusively with the 
Large memory model (code 64K, data 64K). 

The special TEGL Windows Intro Packs provide all of the 
same functions as the complete TEGL Windows Toolkit for 
only $10. Unlike the complete toolkit, the Intro Packs exclude 
all of the system source code and must be ordered for use 
with a specific vendor’s brand of C or Pascal language com¬ 
piler. In keeping with the low cost of the Intro Packs, 
documentation is available only on diskette. 


Victor R. Volkman received a bachelor’s degree in computer science from Michigan Technological University. He is a software 
engineer at C/mage Corporation, Ann Arbor, Michigan, and can be reached at the HAL 9000 BBS, 313-663-4173, 1200/2400/9600 baud 
or via Usenet as vrv@cimage.com. He is also a Contributing Editor for R&D Publications. 





Figure 1 


winframeptr wf; 
twdinit(&wf,100,100,400,300); 
twsetheader(wf,"Window with a Dialog Box' 1 ); 
twdaddlabel(wf,70,10,"Do Things to a File"); 
twdaddcheckbox(wf,20,30,"Use Backup",&btest); 
twdaddradiobutton(wf,20,50,"Load File",&radio); 
twdaddradiobutton(wf,20,70,"Save File",&radio); 
twdaddinputline(wf,20,110,"Fi1ename? ",str,20); 
twdaddbutton(wf,50,150,"OK",ni 1 uni tproc); 
twdaddbutton(wf,170,150,"CANCEL",twdclose); 
twdrawwindowframe(wf); 

Dynamic Dialog Box Initialization 


TEGL Windows works with all CPUs from 8088 to 80486. 
However, I recommend using a 12MHz 80286 or better CPU for 
VGA graphics. The toolkit can be used with any version of DOS 
v3.0 or later. A graphics adapter which supports CGA, EGA, 
VGA, or Hercules is required. I tested TEGL Windows on a 
20MHz 80836 CPU with 4Mb of RAM running MS-DOS V4.01. For 
graphics hardware, I used an old ATI VGA/Wonder (V3) with 
512K RAM, a Princeton PSM-03 analog VGA grey-scale monitor, 
and a Genius GM-6000 three-button mouse. 

Windows 

The TEGL window manager or "supervisor” is responsible 
for properly dispatching all types of events which occur at the 
GUI level. Since TEGL Windows is a completely event-driven 
system, the sole task of the supervisor is to wait for events 
and dispatch the appropriate event handlers. In TEGL Win¬ 
dows, an event handler or callproc is a special type of func¬ 
tion which must receive a window pointer and a mouse- 
status pointer as parameters. The supervisor recognizes six 
basic types of events: mouse click area, click and drag a win¬ 
dow, expand or shrink a window, keyboard events, timer 
ticks, and the CTRL-Break key. 

The supervisor manages all the interaction required to 
move and redraw overlapping windows or "frames.” When the 
user wants to move a window, the supervisor is active from 
when he clicks the right mouse button on a window to when 
the button is released to indicate the new position. If set- 
moveframecallproc() has been installed for that window, 
then the supervisor will call your event handler instead. Your 
window event handler can then actually move the frame by 
calling moves tackimage() and perform other special actions as 
appropriate. 

Window moving can be further inhibited by the set- 
moverestrictions() and setframemobility() functions. The 
setmoverestrictions() function defines a bounding rectangle 
in which a given window must reside. The setframe- 
mobilityO function completely enables or disables move¬ 
ment for a given window. 

If your application needs a higher degree of control than 
allowed by waiting for a mouse click, then you can use the 
setframeentercallproc() and setframeexitcallprocf) func¬ 


tions. The setframeentercallproc() function allows you to 
trigger an event handler whenever the mouse cursor enters a 
particular window. Similarly, the setframeexitcallproc() 
function allows you to trigger an event handler immediately 
after the mouse cursor leaves a particular window. Many 
other low-level window services are available, but all of the 
default actions are capably handled by the supervisor itself. 

Dialog Boxes 

In many GUI-based applications, dialog boxes are crucial to 
gathering information from the user. Most other GUIs, such as 
Microsoft Windows SDK, provide a dialog box editor which 
stores a static representation of the dialog box in a resource 
file. Dialog boxes in TEGL Windows are constructed dynamical¬ 
ly by function calls. This makes designing dialog boxes in TEGL 
Windows somewhat tricky. You must manually determine the 
coordinates and size of each element or "widget.” Further¬ 
more, you must write all of the code to display the various 
widgets before you can see what your dialog box looks like. 
Clearly, some kind of prototyping tool is sorely needed to 
simplify creating and maintaining dialog boxes. 

In TEGL Windows, dialog boxes may be composed of one 
or more check boxes, groups of radio buttons, string input 
boxes, icons, text buttons, and static strings. Since dialog 
boxes are dynamically constructed, each widget in a dialog 
box must be initialized by a function call. Each of these func¬ 
tion calls is denoted by the prefix twd in its name, e.g., twdad- 
dbuttonf). Only text buttons and icons have event handlers 
tied directly to them. Check boxes, radio buttons, and string 
input boxes do not call an event handler when they are pick¬ 
ed or changed. They could be forced to call an event handler, 
however, if they were initialized by the undocumented 
twdadddialogitem() function. A typical example of a dynamic 
dialog box initialization is shown in Figure 1. 

First, the code in Figure 1 initializes the dialog box window 
at the device coordinates (100,100) to (400,300). Next, a win¬ 
dow title is displayed above the dialog by twsetheader(). 
Subsequent widget calls add a static string, a checkbox, two 
radio buttons, and a string input box. Next, an "OK” button is 
linked to a dummy function and a "CANCEL” button is linked 
to the twdclose() function. Finally, the twdrawwindowframe() 
function actually renders the dialog box and all its widgets on 
the screen. Unfortunately, the twddrawwindowframe() function 
is undocumented. 

TEGL Windows includes several canned dialog boxes to 
handle some very common cases. For example, the getyesor- 
no() function will display a string in a dialog box with "YES” 
and "NO” buttons. After a button is selected, the function 
removes the dialog box and returns either TRUE for "YES” or 
FALSE for “NO”. The errmess() function is similar, but simply 
waits for an "OK" click. The selectafile() function solves the 
familiar problem of allowing the user to navigate through 
many subdirectories to find a file. Moving up past the root 
directory allows you to select another drive letter to traverse. 
The setmousesense() function displays a dialog box whereby 
the current mouse x and y “sensitivity" can be altered. Similar¬ 
ly, the asksoundsense() function displays a dialog box for the 
user to adjust the duration of beeps and other sounds. 
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Icons 

TEGL icons are pictures which can be attached to events, 
animated around the screen, or simply displayed as graphic 
illustrations. A TEGL icon can be as big as 100x100 pixels using 
16 different colors. TEGL includes 70 built-in icons that can be 
used by any application. These icons include mainly standard 
dialog box components such as arrows, sliders, and buttons. 
TEGL Windows Toolkit provides an icon editor for creating your 
own icons. 

The icon editor allows you to edit several icons simul¬ 
taneously. Each icon is loaded into a window that can be 
moved about the screen. An icon may be edited at normal 
size or with up to 3x magnification. The icon editor can also 
be used to prepare special icons as mouse cursors. 

The icon editor's menu controls a 
cut/paste buffer which can be merged, 
overlayed, or pasted into the original 
icon or an icon in another window. The 
cut/paste buffer can be rotated in 45- 
degree increments or shrunk prior to in¬ 
corporation into an icon. Other editing 
features include reversing the icon left- 
to-right, color swapping, and changing 
the background color. The actual set of 
colors in the painting palette cannot be 
modified. 

There is a bug in the TEGL Windows 
v2.0 icon editor that causes it to crash 
whenever the Reverse Image or Rotate 
Image functions are selected and the 
cut/paste buffer is empty. A hardware 
reset is required to reboot the machine. 

However, the TEGL Windows vl.10 icon 
editor did not demonstrate this problem. 

TEGL programs can address icons in a 
variety of ways: as a constant data 
block in an Hnclude file, as constant 
data in an assembly language file, or as 
ASCII data in a .DEF file. TEGL provides 
utilities to convert between the various 
formats. No conversion utilities to import 
bitmaps or icons from other graphics file 
types such as .ICO or .PCX are available. 

The definebuttonclickf) function 
displays an icon, makes it clickable, and 
attaches it to an event handler all at 
once. A similar operation is available to 
turn text strings into clickable icons. As 
with window management, many low- 
level services can be used to maintain a 
finer degree of icon control if desired. 


Menus 

Like icons, menus are a highly visible part of a GUI desktop 
environment. The TEGL Windows toolkit contains nearly three 
dozen functions for fine-tuning the look and feel of menus. 
TEGL Windows menuing system is built around the option 
menu and the bar menu. All TEGL menus are created dynami¬ 
cally at run-time. Other GUI systems typically build menus 
with resource compilers or static data structures. 

TEGL Windows option menus are the traditional style of 
menu which presents items in a vertical list. Option menus 
can appear as drop-down menus attached to a bar menu or 
as pop-up menus triggered by another event such as an icon 
pick. The following excerpt from the demo program 
TEGLVIEW.C shows how an option menu can be created: 


ADD THE POWER OF GRAPHICS 
TO YOUR PROGRAMS WITH GENUS 








PCX Programmer s Toolkit 4.0 


€! 


Finally, a programmer's toolkit that helps you 
_ incorporate graphics into your programs quickly and 
easily. The PCX Programmer's Toolkit includes over 90 rou¬ 
tines to display, save, scale, and print PCX bitmapped 
graphics from almost any program. 
.ONLY $ 249 


GX Effects 2.0* 


NEW! 


H Add spectacular special effects (F/X) to your 
2 programs, without being trapped in someone else’s 
editor or slideshow program. Wipe, split, crush, slide, sand, 
drip, diagonal, spiral, random, or explode your graphics. 
Includes new animation support and sprite capabilities. 
.ONLY ^ 1 99 

* PCX Toolkit. GX Graphics, or GX Text recommended but not required. 


GX Text 2.0 


NEW! 


Now you can display blazing bitmapped text in any 
111 graphics mode as simply as text mode. With GX Text, 
you can display your textual information right along with 
your graphical data, using the display or virtual buffers. 
Includes a graphical font editor and 1MB+ of fonts. 
.^.ONLY J 149 


GX Graphics 1.0 


A complete graphics library supporting all graphics 
_ primitives. Use the GX Graphics toolkit instead of the 
BGI or MS libraries and make your program faster, smaller, 
and more portable across compilers - while supporting more 
video modes. 

.ONLY* 199 


To Order Any or All of the Genus 

GX DEVELOPMENT SERIES, CALL TOLL-FREE: 


1 - 800 - 227-0918 

VISA, MASTERCARD, AMERICAN EXPRESS, CHECK, C.O.D., PURCHASE ORDER 


MICROPROGRAMMING 


2900 WlLCREST • SUITE 145 • HOUSTON, TX 77042 • (713) 870-0737 
FAX (713) 8704)288 • BBS (713) 266-9362 
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optionmptr oml, om2, om3; 
om2 = createoptionmenu(fontl4); 
defineoptions(om2, "~0~pen ", 

TRUE, fileselectandview); 
defineoptions(oiri2, 

FALSE, NULL); 

defineoptions(om2, "~Q~uit", 

TRUE, exitoption); 

The createoptionmenu() function ac¬ 
cepts a fontname parameter and 
returns an option menu handle. Since 
all TEQL fonts are stored in the data 
segment, the “font14" points directly to 
its location. All items in the option 
menu assume the same font as the ini¬ 
tial font specified in createoption- 
menu(). The createshadomm() function 
supposedly allows font changes within 
the same menu e.g., to display a menu 
of fonts. However, I was unable get 
createshadowomf) to perform font 
changes successfully within a menu. 

Each call to defineoptions() adds 
another item to the parent menu 
specified in the first parameter. The 
second parameter is the actual text to 
be displayed in the option menu. The 
tilde characters surrounding the letter 
“0" in “~0~pen" are escape characters 
declaring the letter to be a menu ac¬ 
celerator keystroke. When displayed, 
the tilde characters will be omitted and 
the letter underscored. The third 
parameter sets the initial active status. 
If the active status is FALSE, then the 
option item will be displayed in greyed- 
out characters and will disallow menu 
picks. The active status can be changed 
at any time via the entrystatus() 
function. The final parameter to 
defineoptions() is a pointer to the 
event function activated by picking the 
menu item. Option menus automatically 
have scroll "sliders” attached when 
more options are specified than will fit 
on the screen or a pre-defined limit is 
reached. 

In addition to the tilde escape char¬ 
acters, several other embedded charac¬ 
ters modify the look and feel of the 
menu. A greater-than (>) symbol right- 
justifies all text immediately following it. 
Text surrounded by curly braces ({ and 
)), displays in a reduced size font. Last, 
the verical bar (|) jumps to the next 
logical tab setting. 


TEGL Windows bar menus are the 
familiar horizontal style of menu in 
which each item corresponds to a par¬ 
ticular pull-down option menu. Accord¬ 
ingly, option menus are attached to bar 
menus in a similar style as option items 
are attached to option menus. The ex¬ 
ample below integrates the previously 
defined option menus with a bar menu: 

setteglfont(fontl4); 
createbarmenu(0, 0, 639); 
setbarmenumargin(24); 
outbaroption(" ~D~esk ", oml); 
outbaroption(" ~F~ile ", om2); 

Unlike option menus, the text of a bar 
menu is written in the current font 
rather than being parameterized. The 
first two parameters to createbar- 
wenu() are the (X,Y) device coordinates 
of the upper-left corner of the bar 
menu. The third parameter is the length 
of the bar menu in pixels. The setbar- 
menumarginO call tells how many 
pixels from the origin of the bar to of¬ 
fset the first item description. The out- 
boroption() calls actually bind the two 
option menus to the menu bar. Again, 
the tilde characters surround menu ac¬ 
celerator keys. 

In addition to attaching to bar 
menus, option menus can attach to 
other option menus as sub-menus. At¬ 
taching a sub-menu is similar to a 
standard option menu item except that 
the defineoptionssub() is called in¬ 
stead of defineoptions(). If an option 
menu pick is linked to a sub-menu, the 
sub-menu appears immediately to the 
right of its parent menu when ac¬ 
tivated. The presence of a sub-menu is 
signified beforehand by an arrow on 
the far right of the parent option menu 
item. 

Several additional menu customiza¬ 
tion features are available in TEGL Win¬ 
dows. The colors of the bar menu, bar 
menu text, option menu, option menu 
item text, and option menu border can 
all be set globally. Menus can have 
check-mark toggles in the first column 
position maintained via the defineop- 
tionschkf) function. Similarly, groups 
of mutually exclusive check-mark tog¬ 
gles can be maintained by the 
defineoptionsradio() function. 


Fonts 

TEGL Windows provides proportional 
bit-mapped fonts and the functions 
necessary to render text with them. 
TEGL includes 48 bit-mapped fonts in 
the standard library. The fonts include a 
variety of typefaces such as Old English, 
Gaelic, Broadway, Italic, Script, LCD, Sans 
Serif, and Courier. Although TEGL Win¬ 
dows vl.10 only allowed ASCII charac¬ 
ters from 27 to 126, TEGL Windows v2.0 
allows all 255 IBM PC ASCII characters. 
TEGL fonts may be as small as five 
pixels tall and three pixels wide. The 
biggest TEGL font is 24 pixels tall and 
eight pixels wide. TEGL does not provide 
any fonts wider than eight pixels, but 
they expect to provide fonts greater 
than eight pixels by August. 

Unlike most GUI toolkits, TEGL stores 
character data for each font as Defined 
Bytes (db) in a .ASM file. The primary 
advantage is that since they are linked 
into the application program, no addi¬ 
tional resource files need to be dis¬ 
tributed with the executable file. The 
primary disadvantage is that forcing all 
of the font files to be resident increases 
memory overhead at least 40K. Addi¬ 
tionally, if you have several TEGL ap¬ 
plications, the font data is duplicated in 
executable files. TEGL has promised that 
future releases will convert fonts to a 
more conventional binary format. Since 
TEGL does not currently provide a font 
editor, it would be difficult to create 
your own fonts or re-size the existing 
fonts. TEGL has pledged to release a 
font editor at the end of July. 

The TEGL text display functions 
enable you to set the current font, 
write text at an (X,Y) coordinate, return 
the font pixel height, and calculate the 
pixel width of a proportionally displayed 
string before it is rendered. Additionally, 
text can be displayed with special high¬ 
lighting that simulates 3-D with the 
shadowtext() function. All text is dis¬ 
played in the current graphics color and 
justification mode. The settextjus- 
tify() function independently sets left, 
right, or center justification on the verti¬ 
cal and horizontal axes. Although text 
display functions default to proportional 
output, they can be switched to non¬ 
proportional mode by setproportion- 
al (FALSE). The proportionality state is 
global and affects all fonts in use. TEGL 
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fonts must be displayed in their original 
size; no direct font scaling is available. 

The TEGL Graphical Interface does 
not provide vector font support. How¬ 
ever, it can use the Borland Vector Font. 

Timers 

TEGL Windows supports the concept 
of timers as events. As described earlier, 
an event is a callback function that is 
invoked whenever a particular condition 
occurs. In this case, an event is invoked 
when a given timer expires. The resolu¬ 
tion of the TEGL clock is the same as 
the standard INT 08h timer which inter¬ 
rupts about every 55 milliseconds (18.2 
times/second). Since TEGL timers can be 
scheduled up to 64K ticks into the fu¬ 
ture, the longest possible period is 

65535 ticks * acts " 1 h ° ur 

TEGL timer events are automatically re¬ 
scheduled each time they expire. This 
means that you must explicitly call 
droptimercount() to permanently 
deactivate a timer. Alternately, you can 
suspend and resume all TEGL timers 
simultaneously via the timerswitchf) 
function. 

It is important to note that the 
callback function is activated by the 
teglsupervisorf) rather than by the 
timer interrupt handler itself. This 
means that if other timed events be¬ 
come due before your callback function 
has completed, they will simply be 
queued for execution when your func¬ 
tion returns to the teglsupervisorf). 

Virtual Memory 

The TEGL virtual memory manager is 
a library which can be used to auto¬ 
matically move memory blocks be¬ 
tween real memory, EMS memory, and 
disk files. The virtual memory manager 
be used separately or in conjunction 
with the graphics and windowing func¬ 
tions of the toolkit. 

The TEGL virtual memory manager 
likes to have as much of the DOS 
memory heap as possible. It starts out 
by allocating the entire standard heap 
for the virtual heap and then returns a 
small portion back to the standard 
heap. By default, the virtual memory 
manager leaves 10K to the standard 
heap; this is where malloc() and 


Some Assembly Required! 

V Communications has all the tools you need to develop, examine, 
verify, and document assembly-language programs, quicker and 
easier than ever before. 


_ 


v_ 

V 


ASM Checker™ - Locates Coding Problems 

ASM Checker automatically locates common coding errors 
that are often hard to find and easily overlooked. It also 
cross-references external and public symbols and identi¬ 
fies unused symbols and type mismatches. It can save you 
countless hours of debugging time. $179.95 



Sourcer 486 ™ - Commenting Disassembler 

Sourcer creates commented source code and listings from 
memory or executable files. It helps you understand the 
inner details of how programs work. Sourcer output is suit¬ 
able for reassembly, so you can easily make changes or 
correct problems in programs. $129.95 

“Sourcer is the best disassembler we've ever seen!” 

- PC Magazine 


Main BIOS ROM 


VGA BIOS ROM 


DISK BIOS ROM 


BIOS Pre-Processor™ - BIOS Listings 

The BIOS Pre-Processor lets you use Sourcer to obtain 
commented listings for any BIOS ROM in your machine. 
Now you can understand how your specific BIOS works. 
Adds over 75K of comments specific to your BIOS. $49.95 
Sourcer with BIOS Pre-Processor $169.95 (Save $10) 



ASMtool 486™ - Flowcharting and Analysis 

ASMtool makes complex assembly source easy to under¬ 
stand. It automatically creates flowcharts and procedure 
call diagrams that clarify logic paths. It also provides static 
timing analysis for each procedure, register usage 
analysis, and more. $199.95 


More Performance Tools from V Communications 

View-lt™ - Fast, zoomable file viewer, easily view wide $69.95 

132-column documents and assembly listings. 

Unpacker™ - Unpacks packed EXE files and more! $39.95 

ASM ProPak III™ - Sourcer 486 with BIOS, ASMtool 486, $549.70 

Unpacker, View-lt, and ASM Checker. (Save $120) 

Quantasm PowerLib™ - Library of over 300 documented $279.95 
assembly routines with source. (Object only: $89.95) 

Quantasm Magic TSR Toolkit™ - Build your own TSRs. $199.95 
Documented assembly source code and examples. 

C-Clearly® - Formats C source code your way. $129.95 

Memory Commander™ - Complete 386/486 memory $99.95 

manager that provides up to 900K of main DOS memory. 


Specifications: Works on all PC and PC-compatible computers with DOS 2.0 or later. Assembly products sup¬ 
port 8088 through 80486 and math instruction sets and are designed to work with Microsoft MASM or Borland 
TASM assemblers. View-lt requires EGA/VGA/XGA for zoom features. All product names are trademarks of 
their respective companies. 

Shipping and Handling: USA $6; Canada/Mexico $10; Other $18. CA residents add sales tax. VISA/MC/AMEX. 

Call 1-800-648-8266 

V Communications, Inc. 

4320 Stevens Creek Blvd Suite 275 Dept. TS9 San Jose CA 95129 fax 408.296.4441 408.296.4224 
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free() get their memory. The maximum standard heap size 
can be set via setstandardheapsize() and the minimum vir¬ 
tual heap size can be set via reservehugeminimumO. 

The virtual memory manager uses a mechanism called 
“soft locks’’ to guarantee the availability of a memory block in 
use. The virtual memory manager can move any memory 
block around in the virtual heap, EMS memory, or out to disk. 
However, if a memory block has a soft lock, then the virtual 
memory manager must page it back into some part of the 
virtual heap, i.e. directly addressable memory, before returning 
to the application. The vpaccessQ function conveniently 
binds a virtual memory block to the address of a pointer. This 
allows the virtual memory manager to re-assign the pointer at 
will to reflect the real address of the memory block. Of course, 
you must use care when aliasing another pointer to one 
maintained by vpaccess(). 

Other essential functions for virtual memory allocate, free, 
unlock, and clear heap space. The vpgetmem() function is 
similar to mallocf), but can handle blocks greater than 64K. 
The vpfreemem() function is analogous to free(). The 
vpunuse() function declares a block elligible to be paged out 
and breaks the soft lock. The vmpageout() function clears out 
the requested number of bytes from the virtual heap by 
swapping memory blocks out to EMS memory or disk as ap¬ 
propriate. This function can be invoked with very large values 
to force “garbage collection" and defragment the virtual heap. 

The cgetmemO and cfreememf) functions can be used to 
allocate and free memory from the virtual heap which will 
automatically be hard locked. Memory allocated in this fashion 
is always real and can never be swapped out. When cget¬ 
memO is used, the virtual memory manager will automatically 
swap any blocks that are not currently active, to EMS or to 
your disk, thus freeing enough memory to fulfill your request. 
However, if insufficient real memory is still unavailable in the 
virtual heap, then cgetmemO simply returns NULL. 

TEGL Windows Toolkit v2.0 has an improved virtual 
memory manager over vl.10. In prior releases, all of the 
memory behind a given window had to be in one contiguous 
block. The new window manager automatically breaks large 
images into smaller blocks called “parcels." The size of the par¬ 
cel, which defaults to 32K, is also the resolution of the win¬ 
dow manager. You can increase the parcel size, but the win¬ 
dow manager must always be able to allocate twice the par¬ 
cel size from the virtual heap. 

Adapters, Modes, And Drivers 

TEGL Windows supports all popular low-end graphics dis¬ 
play adapters that are compatible with either the CGA, Her¬ 
cules monochrome, Hercules InColor, EGA, VGA, or SuperVGA 
cards. The CGA cards are supported in 640x200 monochrome 
graphics mode only. The Hercules adapters use the standard 
720x348 screen resolution. The EGA cards may be used only in 
the 640x350 mode with 16 colors. The VGA adapters provide 
additional modes for 640x480 in 16 colors and 320x256 in 256 
colors. 

SuperVGA support accomodates all of the aforementioned 
modes plus 800x600, 800x564, and 752x564 resolutions with 


16 colors. SuperVGAs with 512K or more memory can take 
advantage of the 640x480 mode with 256 colors. Due to the 
variances of SuperVGA hardware implementation between 
vendors, the TEGL Windows Toolkit contains special tests to 
determine which brand of SuperVGA is installed. The toolkit is 
able to distinguish between all the various SuperVGA chipsets 
and adapters manufactured by Genoa, Paradise, ATI, Everex, 
Trident, Video-7, Chips 6c Technologies, Tseng, Ahead, Oak, and 
Cirrus. This is accomplished through a combination of poking 
at “unused” VGA registers and hunting for vendor-specific VGA 
BIOS calls. If TEGL Windows supported the VESA SuperVGA 
standard, then all SuperVGAs would be automatically included 
(see bibliography). 

While TEGL Windows admirably supports low-end graphics 
adapters, it lacks support for some of the faster and higher- 
resolution adapters and modes available. The most notable of 
these cards missing support are the IBM 8514/A and XGA and 
any SuperVGA resolutions of 1024x768 and above. Modern 
graphics cards based on the Texas Instruments Graphics Array 
(TIGA) 340x0 CPUs are also not supported. TIGA adapters, such 
as the PepperPro 1280 by Number Nine, are typically capable 
of resolutions of 1280x1024 with 256 colors. Although these 
graphics adapters currently represent a small segment of the 
marketplace, each of them is a challenge to develop device¬ 
independent support. Mr. Brian j. Gorval, President of TEGL Sys¬ 
tems Corporation, told me that support for 1024x768 
SuperVGA modes will be finished by August. He also indicated 
that drivers for 8514/A and TIGA were under consideration, 
but not in any current development plan. 

Whereas most GUI environments require the user to 
choose a graphics driver before starting the environment, the 
TEGL Windows system automatically detects and uses any of 
the supported adapters. The videoautodetect() function 
returns an ASCII string with the name of the highest resolution 
mode available. You can also disable graphics modes accord¬ 
ing to the needs of your application. For example, if you 
decided that your application absolutely had to have at least 
16 colors available, then you could disable CGA and Hercules 
detection by calling setvideochoices(). Unfortunately, both 
videoautodetectO and setvideochoices() are undocu¬ 
mented in the TEGL Windows manual. This is probably be¬ 
cause they are normally taken care of in the standard 
easytegl() initialization call. Code to exclude CGA and Her¬ 
cules would be as follows: 

setvideochoices(TG_CGA,FALSE); 
setvideochoices(TG_HGC,FALSE); 

However, if you want your application to automatically sup¬ 
port several modes, then you will need to load each of the 
drivers which contain them. If you initialize your application 
with the easytegl () function, then it will automatically load 
all four drivers and detect the best mode. If you only want to 
support a subset of graphics modes and want to save 
memory, then you can call the registertgidriver() function 
yourself. For example, the TEGL icon editor will use any mode 
except those with 256 colors. Therefore, it only needs to load 
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three out of four drivers, as shown in this excerpt from 
ICONEDIT. C-. 

registertgidriver(GREVGA16_dri ver); 
registertgidriver(GRCGABW_driver); 
registertgidriver(GRHERCBW_driver); 

Since all four drivers combined are less than 23K, the over¬ 
head imposed by loading extra drivers is marginal. The 
registertgidriverf) function loads and patches in a single 
driver file. A driver has about 20 pointers to graphics functions 
in its jump table of services. The services within a driver will 
read and write single pixels, draw lines, initialize video modes, 
and perform various bitmap block transfers. 

Although TEGL Windows comes close to being device-inde¬ 
pendent, it falls short in the handling of color. According to the 
manual, the actual colors in the display palette are dependent 
on the current graphics driver and mode. Furthermore, if you 
want your application to run both in monochrome and color 
modes, then you must provide color to monochrome transla¬ 
tion yourself. An example of this is shown in the source code 
of the icon editor. 

Documentation And Support 

Previous releases of the TEGL Windows Toolkit included 
documentation solely on the distribution diskettes. TEGL Win¬ 
dows v2.0 comes with a single 260-page spiral-bound tutorial 
and reference book. The tutorial comprises the first one- 
quarter of the book and the reference section occupies the 
remainder. 

The tutorial hastily covers most of the essential areas of 
the toolkit. For example, a bare two pages is devoted to the 
entire topic of menus: pop-up, drop-down, bar, and otherwise. 
Coverage of fonts is completely omitted from the tutorial, but 
is sketched briefly in the README. TXT file provided as an ad¬ 
dendum. The nomenclature of the virtual memory manager 
could use some simplification: at various times, the manual 
refers to a particular memory area as the TEGL heap, the huge 
heap, and the virtual heap. Similarly, another memory area is 
alternately referred to as the normal heap, the standard heap, 
and the regular heap. 

The tutorial provides listings of only two very short 
programs in the actual text. Although the source code for 
more than two dozen example programs comes with TEGL 
Windows, none of them are referenced by the tutorial. The 
tutorial could also greatly benefit from inclusion of short code 
fragments to demonstrate related functions. Though the TEGL 
Windows toolkit vl.10 reprinted many short programs in the 
text of the manual, these are notably omitted in the v2.0 
manual. 

The reference section of the manual is simply an exhaus¬ 
tive alphabetical listing of the nearly 400 functions provided 
by the toolkit. For each function, the manual provides an ANSI 
C function prototype, level indicator, source filename, general 
remarks, and a "see-also” list of related functions. The level 
indicators range from zero to three: zero signifies internal 
functions that you ordinarily rarely call directly; level three sig¬ 
nifies direct object manipulation functions, e.g., closewin- 
dow(). The general remarks consititute the main source of in¬ 
formation and vary from as short as one sentence to as long 


as several paragraphs. The “see-also” list is important for locat¬ 
ing related functions. 

The overall structure of the reference section could be im¬ 
proved easily by partitioning the functions into related groups. 
The existing solely alphabetical organization could be daunting 
to novices unfamiliar with the toolkit. A more effective or¬ 
ganization would place all the menu function descriptions in a 
chapter about menus, for example. Since the index lists only 
function names, it can be difficult to find a function that does 
exactly what you want. 

Both the tutorial and reference sections are devoid of 
graphic illustrations. Illustrations are badly needed for all 
aspects of the GUI toolkit such as windows, graphics drawing 
primitives, fonts, menus, and dialog boxes to name a few. Il¬ 
lustrations would also improve readability by breaking up 
large sections of text. 

The book contains numerous typographical errors 
throughout the text. Some examples are references to the 
“Boland compiler" (sic) and the “Borlard Graphics Interface” (sic). 
Additionally, the description of the setpalette() function 
makes a reference to the as-yet undocumented 
setallpalette() function. As mentioned earlier, several of 
the demonstration and utility programs call functions which 
are missing from the manual. 

According to Mr. Brian J. Gorval, president of TEGL Systems 
Corp., they will provide unlimited free technical support by 
telephone and fax machine. TEGL Systems will review users 
code if they have problems with the toolkit. The code review 
service is limited to identifying problems and suggesting 
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The universal library for building 
fast graphical displays for data 
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displays, strip-charts, annunciators, alarms, signal 
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allow programs to run unmodified on over 27 video modes! 
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solutions. However, TEGL Systems does not provide a consult¬ 
ing service nor write applications for toolkit users. 

TEGL Systems Corporation notifies registered users of major 
upgrades. Depending on the situation, upgrades range from 
free of charge to up to 60 percent of the list price. The 
upgrade price from TEGL vl.10 to v2.0 is simply the difference 
in the list prices between these two product versions. 

TEGL Systems Corporation also offers technical support on 
its BBS at (604) 681-8769. Additionally, you can send e-mail to 
Richard Tom, Vice-President of Product Development. He can 
be reached by EASYPLEX on CompuServe as userid 74370,2354. 

Performance 

The most striking difference between TEGL and traditional 
GUI toolkits, such as MS Windows SDK, is that you need far 
less initialization and setup of data structures and event han¬ 
dling in TEGL. After setting up your dynamic menus, simply 
calling the tegleasyO function is sufficient to initialize the 
entire GUI environment. After leaving the teglsupervisorf), 
the graphics environment is returned to its initial state. The 
CTRL-break handler is automatically captured and issues a 
shutdown message to the supervisor when this key sequence 
is hit. 

The TEGL Windows system captures several interrupt hand¬ 
lers to provide some of its most important services to the 
application: keyboard (09h), timer ( 08h ), CTRL-break ( lBh ), and 
CTRL-C (23b). However, TEGL failed to handle a DOS critical 
error trap (INT 24h) during the selectafile() canned dialog 
box. When I attempted to access a file on a floppy drive sans 


C Communications Toolkit 


and CRC rc 


Now you can add professional serial communications to any C 
application. C Communications Toolkit makes it fast and easy. 
You don’t need to spend months writing, testing and debugging 
low-level device support, file transfer protocols and CRC rou¬ 
tines. 

Power 

Speed: up to 115,000 bps. 

Flow control: XON/XOFF, RTS/CTS, DTR/DSR. 

Interrupts: Receive, Transmit, Modem Status, Line Status. 

Modem Support: Full Hayes command set + Telebit & UDS extensions. 
Terminal Emulation: VT52. VT100, ANSI X3.64. ANSI.SYS. 

Full DCA/Intel CAS support (FAX and file transfer). 

Flexibility 

Supports an unlimited number of serial ports. 

Supports any I/O address and IRQ line. 

Log output and/or input to a printer. 

Capture output and/or input to a buffer and/or file. 

Multi-port board support for AST, Digiboard, Commtech, Arnet, etc. 

File Transfer 

Single file: ASCII. XMODEM, XMODEM-CRC, XMODEM-lk. 

Multi-file: YMODEM, YMODEM-g (for error-free links). 

KERMIT (with run-length encoding and 8th—bit prefixing extensions), 

Communications Chip Support 

INS8250/A/B, 16450. 

INS16550/A (including FIFO buffers and interrupt threshold). 

Zilog Z-80 SIO/DART (async., SDLC, HDLC, BiSync). 

Documentation 

Over 200 functions. 600-page manual with 100 pages of Toolkit tutorial 
(build a powerful terminal program in easy stages), 125 pages of serial com¬ 
munications background and over 35 example programs. 


Supports: MSC 5.0+/Quick C, Power C V1.2+, Turbo C, Watcom C. 

Full source code included — No run-time royalties. 30-day warranty. 

CALL (214) 226-6909 

FAX: (214) 226-0386 BBS: (214) 226-8088 



Magna Carta Software 
Inc. 

P.O. Box 475594, 
Garland, TX 75047-5594 


omy $-149.95 


(in TX add 8% sales tax) 
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disk, I received the text Disk not ready: Abort, Retry, 
Ignore blasted over the graphics. I chose Abort and TEGL ex¬ 
ited ungracefully necessitating a reboot. 

The most visible performance aspect of a GUI is how well 
its window manager handles refreshes. The TEGL window 
manager uses a sophisticated algorithm to determine exactly 
how much of the screen needs refreshing when overlapping 
windows are moved or re-sized. I tested the case of refreshing 
a window of text where the entire window must be erased 
and re-drawn. Refreshing a window nearly the entire size of 
the VGA screen required only about 3.0 seconds on a 16-Mhz 
80386. The equivalent refresh on a 8MHz 80286 with an ATI 
EGA/Wonder took 3.8 seconds. Accordingly, I recommend at 
least a 12MHz 80286 to run TEGL Windows applications with 
VGA graphics. 

Compared to the heavyweight graphics toolkits, such as 
HALO '88 and GSS'CGI (see bibliography), TEGL windows falls 
short on support of locator and hardcopy device drivers. 
Locators other than mice, such as joysticks, graphics tablets, 
and light pens, are not supported in TEGL Windows. Both HALO 
’88 and GSS*CGI support several devices in each of these 
categories. Support for hardcopy output device drivers is com¬ 
pletely omitted from the TEGL Windows system. At the very 
least, a screen-dump type of function should be provided. At a 
higher level, hardcopy output device drivers should be 
loadable in the same way that graphics screen adapter 
devices are. Accordingly, the graphics primitives would then 
render their output in a bitmap buffer that would eventually 
be written to the device. Both HALO '88 and GSS‘CGI provide 
this kind of services for hardcopy output devices, including 
dot-matrix printers, ink jet printers, laser printers, pen plotters, 
electrostatic plotters, and film recorders. 

Conclusion 

TEGL is a relatively sophisticated single-tasking window en¬ 
vironment at a minimal cost. The toolkit requires relatively 
little RAM compared to competitive GUIs and supports most 
popular displays. Since TEGL includes complete source code, it 
would be an excellent choice for an instructional tool. The 
only weak points about the product are the manual and 
hardcopy output support. □ 
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Windows 3: A Developer’s Guide 


Reviewed By Ron Burk 


Windows 3: A Developer’s Guidejeffrey M. Richter, M6 lT Books. 
Book only: $29.95, ISBN 1-55851-162-8. Book/Disk Set: $39.95, 
ISBN 1-55851-164-4. Shipping/Handling $3.75 


The dearth of books for Windows programmers has turned 
into a stream of books, and the flood is in sight. Windows 
programming is a large enough topic that your opinion of any 
particular book may be largely influenced by what you are 
working on. For example, I have preferred Paul Yao and Peter 
Norton’s book over Petzold's because the work I was doing 
required a good understanding of Windows v3.0 memory 
management (Petzold pretty much stuck with his Windows 
v2.0 explanations), when I moved on to my next project, I 
revised my opinion of Petzold’s book upward, since it 
answered the very questions the new project raised. 

In Windows 3: A Developer's Guide, Jeffrey M. Richter has 
produced a code-intensive book aimed at the developer who 
is already familiar with basic Windows concepts. The code 
aims to supply examples and reusable functions that fill gaps 
between the bare-bones Windows API and a professional¬ 
looking Windows application. The book sticks to practical and 


useful code and contains few theoretical discussions. The best 
way to describe the book is to list the code described in each 
chapter. 

Anatomy Of A Window 

This chapter discusses the basics of Windows windows. 
The centerpiece of the discussion is a utility called Voyeur 
(Figure 1). Voyeur does for windows what Spy does for mes¬ 
sages. You can use Voyeur to inspect the attributes of any 
other window (including dialog boxes and controls) on the 
screen. 

The title of the chapter may sound introductory, but it ac¬ 
tually covers a lot of ground. The chapter starts with descrip¬ 
tions of window attributes, window life cycles, and messages, 
but moves on to describe Voyeur, which is no introductory 
Windows program. Voyeur has to be able to change the 
shape of the cursor, capture all mouse clicks, and locate and 
draw a frame around any visible window. This utility may be 
worth the price of the book. It is just the right tool for the job 
if you want to study other applications’ windows so you can 
modify their behavior. In fact, that is exactly what happens in 
the next chapter. 


Ron Burk has a B.S.E.E. from the University of Kansas and has been a programmer for the past 10 gears. You mag contact him 
at Burk Labs, P.O. Box 3082, Redmond, WA 98073-3082. 
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- CLASS INFORMATION * 
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* WINDOW INFORMATION * 

Window (hWnd): 0x1580. Program Manager 

Creator (Inst): 0x0856. C:\WIN3\PROGMAN.EXE 

Parent (hWnd): (no parent window) 
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Location: (0. 0)-(640, 416), Dim=640x416 

Wnd styles: 0x14CF0000 Ext styles: 0x00000000 


Extra bytes: 0 
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The Voyeur Utility 


Subclassing And Superclassing Windows 

The code example that illustrates subclassing is called Pro¬ 
gram Manager Restore. Suppose you set the ''Minimize on 
Use” option in the Program Manager and then use it to ex¬ 
ecute a single program. When that program terminates, you 
more than likely will want to restore the Program Manager. 
Program Manager Restore is a little utility that modifies the 
Program Manager so that it automatically restores itself under 
the conditions just described. 

Part of the code includes a function that locates the first 
window of a specified window class that has a specified 
name. The chapter demonstrates superclassing by superclass¬ 
ing an EDIT control to create a new control that does not 
allow alphabetic characters. That is not terribly useful in itself, 
but the example contains some reusable functions that ease 
the task of superclassing windows. 

Sadly, Program Manager Restore may be an all too realistic 
example of how Windows subclassing is used in practice. To 
attack and modify an existing application like Program 
Manager, you have to use utilities like Spy and Voyeur to dis¬ 
cover program internals, such as window class names, menu 
IDs, control IDs, etc. Once you write code that depends upon 
the internals of another program, that code is always in 
danger of breaking with every new release of the other pro¬ 
gram. 

Dialog-Box Techniques 

This chapter offers several tricks of the trade related to 
Windows dialog boxes. The first section shows how to con¬ 
struct folding/unfolding dialog boxes. You have probably seen 
such boxes with a big button in the corner, perhaps labelled 
“Options >." When you press the button, the dialog box ex¬ 
pands and reveals more controls. This style lets you separate 
options into two groups: the most commonly used and the 
less commonly used. The user then doesn’t have to face an 
array of advanced options unless it is really necessary. 


The second section of the chapter 
describes something the author calls 
“modalless" dialog boxes. These are dialog 
boxes that look modal to the user, but 
look modeless to the programmer. The ad¬ 
vantage over a simple modal dialog box is 
that you can just hide the box when it is 
not being used, rather than destroying it. 
That way, the next time you display it, all 
the control values are still intact. With a 
normal modal dialog box, you would have 
to maintain a parallel set of global vari¬ 
ables to make the box “remember" its pre¬ 
vious settings. The code includes reusable 
functions for "modalless" dialog boxes that 
are analogous to the Windows API func¬ 
tions for modal dialog boxes. 

The chapter closes by demonstrating 
how to construct dialog boxes on the fly. 
Normally, you use dialog boxes compiled 
into your program that never change. 
Some programs, however, need dialog 
boxes whose structure cannot be known 
in advance. For example, a database program might want to 
allow a user to define a new table and then automatically 
produce a dialog box based on that table description. 

Designing Custom 
Child Controls 

Windows allows you to add to the list of built-in controls 
(edit boxes, list boxes, buttons, and so on) by building custom 
controls. This section illustrates the issues and techniques in¬ 
volved by constructing two custom controls: a meter control 
(suitable for showing percentage completion of a task) and a 
spin button, which allows the user to cycle through a list of 
values. 

Custom controls require more than a little thought and 
code. The spin button code is particularly useful, since the CUA 
guidelines define them but Windows does not supply them. 
The chapter also goes through the steps necessary to make 
your custom control compatible with dialog editors. 

Setting Up Printers 

This chapter describes how Windows manages printers and 
how your application can access various printer parameters. 
Like most areas of Windows programming, printing has its 
own set of problems and ways of getting around them. The 
chapter includes enough code to create a “Printer Setup" 
dialog box. Most Windows applications that use the printer 
include such a dialog so that the user does not have to go to 
the control panel to select or enable a printer. 

Tasks, Queues And Hooks 

This chapter contains a conceptual discussion of Windows 
tasks, queues (the system queue and application queues), and 
hooks (the ability to intercept messages). An example screen 
blanker uses a hook to detect that the user has typed nothing 
for a certain period. The other code example in this section is 
a macro recorder. You can use this to add a macro facility to 
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your application so the user can record and playback 
keystrokes. 

MDI Application Techniques 

The Windows Multiple Document Interface is documented 
in the Windows SDK documentation and briefly discussed by 
Petzold. Again, this book addresses topics that other books do 
not and that many programmers stumble over. This section 
shows you how to add a status bar to your MDI window that 
can be turned on or off. It also shows how to use that status 
bar to implement menu bar help, so that when you select a 
menu item, a line of help text appears in the status bar. 

This section also covers custom tiling. Some MDI applica¬ 
tions can be smarter about tiling windows than the default 
Windows tiling. For example, an interactive debugger might 
always give a source code window a bigger tile and a register 
window a smaller, longer tile. 


Installing 

Commercial Applications 

The final chapter is all about Windows installation 
software. Users expect to buy Windows software that installs 
itself, showing the percentage of completion as it is copying 
files, and notifying the Program Manager of any new program 
groups completed. 

This chapter illustrates these topics with SETUP, a complete 
Windows installation program. You can even use this applica¬ 
tion as it stands, since it reads a text file that describes what 
installation floppies contain which files. SETUP handles all the 
file copying and the DDE conversation with the Program 
Manager. All you have to do is type in a configuration file. 


AT BUS DESIGN 


At last, here is the timing book for the XT and AT 
Bus. Detailed text, tables and diagrams tell you what 
each signal line is for, what it does and when it does 
it. All the information is compatible with the IEEE 
P996 Specification for the ISA (AT) Bus. In addi¬ 
tion, the 8 and 16 bit parts of the EISA Bus are 
included. AT Bus Design, by Ed Solari, has over 200 
pages, with more than 100 figures and tables. Handy 
7” x 9" format, soft cover, $69.95. 


URF'E We'll include a free copy of the pocket- 

sized XT-AT Handbook by Choisser 
and Foster with each AT Bus Design book if you tell 
us where you saw this ad. Of course, this $9.95 value 
is also available by itself. Or buy five or more for only 
$5.00 each. 


VISA 


800-462-1042 

619-271-9526 


Annabooks 

12145 Alta Carmel Ct„ Suite 250 
San Diego, CA 92128 


FAX 619-592-0061 
Money-back guarantee 
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Summary 

The code supplied on the floppies is unfortunately specific 
to the Microsoft C compiler. I spent about 30 minutes fiddling 
with just one of the demonstration programs, trying to con¬ 
vert it to Zortech C. After changing all the non-ANSI 7/" com¬ 
ments to 7**/” comments and twiddling makefile formats and 
compiler options, I finally gave up. I decided to just use the 
code in the book for ideas instead of as a starting point for 
writing my own code. If you use Microsoft C for Windows 
development, the floppies are a handy addition to the book; if 
you use other compilers, count on some conversion time to 
make the code compiler-independent. The introduction does 
point out that Microsoft C v6.0 is required for the code in the 
book, but in a code-intensive book like this, a subtitle like 
“With Examples in Microsoft C 6.0” might be more appropriate. 
Fortunately, the disks contain the executables for all of the 
sample programs, so you don’t have to have Microsoft C to 
take advantage of the Voyeur utility. 

This book is not introductory and it is not comprehensive. 
It is a hands-on set of code examples that illustrate techni¬ 
ques used by many commercial Windows applications. If you 
want your application to take advantage of the techniques 
described in this review, the book will save you many hours 
of head-scratching and thumbing through the Windows SDK 
documentation. Looking at other people’s code is still a good 
way to improve your own-, you can copy their good ideas and 
avoid their mistakes. Windows 3: A Developer's Guide provides 
a decent amount of useful code for you to examine, modify, 
learn from, and improve on. □ 
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"Serialtest is a lifesaver..." 

INFOWORLD, 29 May 1989 


Serial 

Communication 

Problems? 

Take the guesswork out of communications troubleshooting. 
For $295 Serialtest® software turns your PC into a data line 
monitor. Serialtest shows you exactly what information is 
flowing between any two devices-both data bytes and control 
signals. An interactive mode allows sourcing one side of the 
communications link. All necessary cables for both monitor 
mode and source mode are included. 

Features: timestamping; triggers; capture to disk; display in 
hex, ASCII, EBDCIC, and Baudot, autobaud; graphic signal 
display; error reporting; printed dumps; pattern search; 
CRC/checksum calculations; configuration management; 
user-defined nonstandard baud rates; many others. 

Serialtest works better and has more features than any other 
software serial data analysis package. If you work with serial 
communications, there is no wiser investment than Serialtest. 

Order Serialtest today, or request a free demo disk. 

Also, ask us about SerialBERT®, our new package that turns 
your PC into a Bit/Block Error Rate Tester. 

Frontline" 

by Progressive Computing 

Progressive Computing, Inc. Tel (800) 562-8378 

814 Commerce Drive (708)574-3689 

Oak Brook, IL 60521 FAX (708) 574-3703 
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Programming Communications 
Under Windows 


David T. Lowerre 


Windows provides a set of functions for serial I/O. Windows 
applications that use the serial port must use these functions 
to be "well behaved." This article describes the use of these 
functions by encapsulating them into a set of functions that 
hide the Windows-specific details from the rest of the applica¬ 
tion. The result is Listing 1, which provides high-level support 
for serial communications under Windows through a simplified 
interface. 

The multitasking nature of Windows requires special con¬ 
siderations to maintain the integrity of a data link without 
locking out other applications. A communications program 
must regularly check for activity at the serial port to avoid 
losing data, but a polling scheme will not work under Windows 


without locking out other applications. This article will discuss 
one strategy for ensuring that a communication program can 
keep track of incoming data without monopolizing system 
resources. 

Handles And Ports 

Windows keeps track of almost everything through “hand¬ 
les” and the serial ports are no exception. In this case, a handle 
is an integer value greater than or equal to zero. A Windows 
“port” is made up of several things: a set of hardware registers, 
an interrupt handler, and a pair of First-In-First-Out (FIFO) 
queues. Luckily, Windows manages these for you and all you 
need to keep track of is a handle. 

The first declaration in Listing 1 is an 
array of handles, all initialized to -1 and 
declared static, since no one else needs 
to access them. Since Windows supports 
four ports you need at least four handles, 
but the array comhandle contains five 
elements so you can use the port num¬ 
ber as an array index. All of the functions 
in Listing 1 expect an integer parameter, 
port, to identify the port to operate on. 




David T. Lowerre has seven years of programming ex¬ 
perience, mostly at Interstate Electronics Corporation, where he 
is currently working in real-time data analysis applications and 
embedded systems programming. He also has experience in 
CAD applications programming, language development, and 
automated hardware and software testing. In his spare time, 
he works in Windows application development. 
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Figure 1 

char buf [128], *bufptr; 
int bytesRead, bytesWritten; 

/* attempt to read 128 bytes from port 1 */ 
bytesRead ■ ComRead( 1, buf, 128 ); 

bufptr = buf; /* point at the buffer */ 

/* send whatever was read to port 2 */ 
while( bytesRead ) 

{ 

bytesWritten = ComWrite( 2, bufptr, bytes_read ); 
bufptr +■ bytesWritten; /* adjust pointer */ 
bytesRead -= bytesWritten; /* adjust count */ 

} 

An Example of Windows Serial I/O 


Figure 2 

char buf[128], *bufptr; 

/* wait for a block of data */ 
while( ComInQSize( 1 ) 128 ) 

ComRead( 1, buf, 128 ); 

/* wait till output queue can handle it */ 
while( 512 - ComOutQSizef 2 ) 128 ) 

ComWrite( 2, buf, 128 ); 

Using the Queue Functions to Avoid Overflow 


Opening And Closing Ports 

To prepare a port for use, you must open it by calling the 
Windows function OpenCommO. The function ComOpenf) in List¬ 
ing 1 performs this call. Windows expects a string to identify 
the port (“COM1", "COM2", and so on), so ComOpen() builds the 
appropriate string using sprintfO and the port number sup¬ 
plied. 

You tell Windows how big to make your input and output 
FIFOs by passing along the values inqsize and outqsize. This 
allows the application to learn the size of these queues. Win¬ 
dows allocates the memory for these queues out of its magi¬ 
cal memory pool so you could make these large if you 
wanted, but there really shouldn’t be a need. 

If everything goes as planned, Windows returns a handle 
that is positive and ComOpen() puts it in the handle array and 
then returns with a value of one. However, if something is 
wrong, Windows returns a negative value, which ComOpen() 
displays before returning with a value of zero. The function 
error() is my own, not a Windows function, and it accepts 
arguments for printfO, shoves them into a string and then 
displays the string in a dialog box. 

The ComOpen() function can be called as follows: 

if( ComOpen( 1, 1024, 512 ) ) 

{ 

/* Go on and use the port ... */ 

} 


When you finish using the serial port, you must close it or 
else Windows won’t let anyone else use it! The function Corn- 
Close () does this by first making sure that the port is open 
and then calling the Windows function CloseComm() with the 
port handle. Finally, ComClose() sets the handle to -1 to indi¬ 
cate that the port is no longer open. 

Setting Communication Parameters 

The communication parameters (baud rate, parity, data 
bits, and stop bits) can be set using the Windows control 
panel. But just in case you want to do it yourself, you have 
the function ComSet(). To modify the port settings, ComSet() 
calls the Windows function GetCommStateO to obtain a 
Device Control Block (DCB). ComSet() can then modify the DCB 
and pass it to the Windows function SetCommState() to up¬ 
date the port’s parameters. 

The parameters themselves are interesting. The baud rate 
is the actual number of bits per second (9600 for instance) at 
which to operate. Data bits are specified the same way, ex¬ 
plicitly. Parity and stop bits are different though. ComSet() 
maps zero, one, and two into correct Windows constants to 
set the parity and stop bits. 

To set the parameters to 2400 baud, no parity, one stop bit 
and eight data bits: 

ComSet( 1, 2400, 0, 8, 0 ); 
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Listing 1 ( comm.c ) 

/* 

Comm.c - Generalized Communication functions 
Author - 2/16/91 David T. Lowerre ;( 

2/16/91 Windows version 

*/ 

#include <stdlib.h> 
finclude <windows.h> 

static int comhandle[5]= {-1,-1,-1,-1,-1}; /* support up to com4 */ 

/* 

Open a communication port 

*/ 

ComOpen( int port, 

int inqsize, 
int outqsize ) 

{ 

char comstr[5]; 
int handle; 

sprintf( comstr, "C0M%d", port ); 

if( (handle = OpenComm( comstr, inqsize, outqsize )) < 0 ) 

{ 

error( "Failed to open %s: code %d", comstr, handle ); 
return 0; /* indicate failure */ 

) 

comhandle[port] = handle; /* store the new handle */ 
return 1; /* indicate success */ 

} 

/* 

Close a communication port 

*/ 

void ComClose( int port ) 

( 

/* Make sure that we have opened the port */ 
if( comhandle[port] >» 0 ) 

1 

CloseComm( comhandle[port] ); 

comhandle[port] « -1; /* mark the port as closed */ 

} 

) 

static char ptyval[] = { NOPARITY, EVENPARITY, ODDPARITY }; 
static char stpval [] = { 0NEST0PBIT, 0NE5ST0PBITS, TWOSTOPBITS }; 

/* 

ComSet - Set Communication Parameters 

*/ 

void ComSet( int port, /* port number */ 

int baud, /* actual baud rate */ 

int parity, /* 0,1,2 for NONE,EVEN,ODD */ 

int bits, /* actual number of data bits */ 

int stop ) /* 0,1,2 for 1, 1.5, 2 */ 

{ 

DCB deb; 

if( comhandle[port] >= 0 ) 

{ 

/* Get the DCB from Windows */ 

GetCommState( comhandle[port], (DCB FAR *)&dcb ); 

dcb.BaudRate = baud; 

dcb.ByteSize = bits; 

deb.Parity = ptyval[parity]; 

dcb.StopBits « stpval[stop]; 

/* Use the new DCB to set up the port */ 

SetCommState( (DCB FAR *)&dcb ); 

) 

} 

/* 

ComRead - Read from the input FIFO of a port 

*/ 

Interface to Windows Serial I/O 


/* Port number */ 

/* input FIFO size */ 
/* output FIFO size */ 


Reading And Writing 

Windows handles the individual byte 
reception interrupts and puts the in¬ 
coming data into an input queue. You 
can then read it out in chunks to save 
overhead. The function ComRead() does 
this by calling the Windows function 
ReadComm(). 

Both ComReodO and the Windows 
function ReadComf) expect a pointer to 
a buffer to put the data and a count of 
the number of bytes to attempt to read. 
If fewer bytes are available than re¬ 
quested, Windows copies them to the 
buffer and returns the number of bytes 
actually read. If the return value is 
negative, then an error occurred (like a 
parity, framing, or overrun error.) The 
absolute return value still represents the 
number of bytes read. 

If ReadCommO returns an error (a 
negative value), then you must call Get- 
ComError() to clear it. Otherwise, the 
port will cease to function properly. As 
written, ComRead() ignores the error 
after calling the GetCommError() func¬ 
tion to clear it. This probably would be 
considered bad form for non-trivial ap¬ 
plications. 

The ComUrite() function is almost 
the same as ComRead () except that it 
calls WriteComm() to copy the re¬ 
quested number of bytes from the 
given buffer into the output queue. 
Note however that this does not mean 
that when the function returns Win¬ 
dows has transmitted all the data. In 
clock cycles, it will be a long time 
before all of this data has been moved 
across the serial interface. Once again, 
Windows handles the details of the 
asynchronous I/O. You need only take 
care not to overflow the queue or close 
the port before the queue is empty. If 
the output queue is full or nearly so 
when you attempt to write to it, the 
return value from ComUrite will not 
equal the number of bytes you wanted 
to send. The ComRead() and ComUrite() 
functions can be called as shown in Fig¬ 
ure 1. 

Monitoring Queues 

Though the above scheme can work 
in some cases, most of the time it is 
more useful to find out how much data 
is in a queue before attempting to read 
from or write to it. The ComInQSize() 
and ComOutQSize() functions provide 
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this information. Both functions call the 
Windows function GetComErrorf) to 
get a COMSTAT structure. (Note that Corn- 
Read () and ComWrite() supplied NULL 
for this parameter since they did not 
use it.) Among other things, the COMSTAT 
structure specifies how many bytes are 
in both the input and the output 
queues. Figure 2 shows how to use 
these functions to simplify the code in 
Figure 1. 

GetMessagef) And Input 
Focus 

The preceeding examples for reading 
and writing are a good example of how 
not to structure a well-behaved com¬ 
munication program under Windows. 
Windows applications multitask by 
yielding control to Windows and other 
applications. Windows will not preempt 
a windows application, which means 
that in the above example the whole 
system is waiting in those while loops. 

The solution is to structure your 
serial port handling as a fallthrough 
function that acts when the queues are 
ready and continues when they are not. 
That way you can continue to call the 
Windows function GetMessagef) , which 
yields control as a well-behaved Win¬ 
dows program should. 

But what happens when you yield 
control? You very possibly could lose 
the input focus. Windows is basically 
structured around the idea of a user in¬ 
terface. Having the input focus means 
that the user is interacting with your 
application and you get lots of mes¬ 
sages and therefore, lots of CPU time. 
But if the user stops interacting with 
your application or puts another win¬ 
dow on top of yours you may stop get¬ 
ting input messages altogether. So 
what? Well, Windows will keep collect¬ 
ing your incoming serial data, so that is 
OK but if you don't read the data out of 
the queue occasionally it will overflow 
and you will lose data. 

Here is one way to help your ap¬ 
plication get control regularly. In the ap¬ 
plication initialization function, Init- 
Application(), place a call to the Win¬ 
dows function SetTimerf). This function 
will allocate a timer that sends a mes¬ 
sage to your application at regular inter¬ 
vals. For my application, my input 
queue is more than big enough to hold 
one second's worth of data, so I have 
the timer send a message every 
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Listing 1 - Cont’d 

ComRead( int port, /* port number */ 

char *buf, /* place to put the data */ 
int bytes ) /* number of bytes to read */ 

{ 

int read; /* number of bytes actually read */ 
int err; 

if( comhandlefport] >= 0 ) 

( 

/* if the return value is negative, clear the error */ 
if( (read = ReadComm( comhandlefport], buf, bytes )) <= 0 ) 
err = GetCommError( comhandlefport], NULL ); 
return abs(read); /* return number of bytes actually read */ 

) 

else 

return 0; /* port not open, nothing read */ 

} 

/* 

ComWrite - Write to the output FIFO of a port 

*/ 

ComWrite( int port, /* port number */ 

char *buf, /* source of data to move into FIFO */ 

int bytes ) /* number of bytes to write */ 

( 

int wrote; /* actual number of bytes written */ 
int err; 

if( comhandlefport] >= 0 ) 

( 

/* if the return value is negative, clear the error */ 
iff (wrote = WriteComm( comhandlefport], buf, bytes )) <= 0 ) 
err = GetCorimErrorf comhandlefport], NULL ); 
return abs(wrote); /* return actual number of bytes written */ 

) 

el se 

return 0; /* port not open, nothing written */ 

) 
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Listing 1 - Cont’d 

/* 

ComlnQSize - Determine the number of bytes waiting in the input FIFO 

*/ 

ComInQ$ize( int port ) 

{ 

COMSTAT cstat; 
int err; 

if( comhandle[port] >= 0 ) 

{ 

/* catch the COMSTAT information in cstat */ 

err = GetCommError( comhandle[port], &cstat ); 

return cstat.cblnQue; /* number of bytes in the FIFO */ 

} 

else 

return 0; /* port not open, no bytes in FIFO! */ 

} 

/* 

ComOutQSize - Determine the number of bytes remaining in the 
Output FIFO. 

*/ 

ComOutQSize( int port ) 

( 

COMSTAT cstat; 
int err; 

if( comhandle[port] >= 0 ) 

{ 

/* Catch the COMSTAT information in cstat */ 

err « GetCommError( comhandle[port], &cstat ); 

return cstat.cbOutQue; /* number of bytes in the FIFO */ 

} 

else 

return 0; /* port not open, no bytes in FIFO! */ 

) 

/* End of File */ 


second. Note that timers are a limited 
global resource so SetTimer() may 
return 0 saying that it can't give you 
one. Also, make sure to save the value it 
returns when it is successful since this is 
what you use to call KillTimerf) when 
you finish. 

Although a timer can give you control 
when another application has the input 
focus, Windows can't generate timer 
events unless some application yields 
control of the CPU. In other words, 
another application can still hog the CPU 
and keep your application from getting 
the timer events it needs to service the 
queues. Until Windows offers preemptive 
multitasking, being at the mercy of mis¬ 
behaved Windows applications is just a 
fact of life. 

Conclusion 

Using Windows communication func¬ 
tions is at least as easy as using a third- 
party library of communication functions. 
However, by encapsulating the Windows 
specifics, you can make your application 
more portable. I wrote the same applica¬ 
tion for Windows and for DOS and, at 
least for the communication functions, all 
I had to rewrite was the functions in 
Listing 1. □ 
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Preventing Lost Keystrokes 

David Burki 


Preventing DOS From Losing Keystrokes 

The PC keyboard interface has undergone significant 
changes since it was first introduced. Keyboards now have 
more keys and the BIOS supplies new functions for access¬ 
ing them. Although the software interface to new key¬ 
boards is almost backwardly compatible, there are a few 
glitches. One of those glitches is that, under the right condi¬ 
tions, DOS may lose keystrokes. After a quick review of 
keyboard basics, this article describes how DOS loses 
keystrokes and provides a TSR that corrects the problem. 

Keyboard Basics 

The BIOS maintains a 15-key internal buffer (BIOS key¬ 
board buffer) where the BIOS keyboard hardware interrupt 
(INT 9) stores keystrokes received from the keyboard and 
from which programs (including DOS) may retrieve 
keystrokes utilizing the BIOS keyboard interrupt (INT 16h). 
The BIOS stores keystrokes as word values within the BIOS 
keyboard buffer. The high byte of each word (keycode) 
contains a scan code that uniquely identifies a physical key 
on the keyboard and, if the keystroke was an ASCII charac¬ 
ter, the low byte contains the ASCII code. 

When IBM introduced the original PC, the keyboard in¬ 
terface was fairly simple. A scan code generated by a key 
press or release was transferred to the keyboard controller, 



read by the BIOS keyboard hardware interrupt (INT 9), and 
placed into the BIOS keyboard buffer. The high byte of the 
keycode generally contained the original scan code sent by 
the keyboard and, if the key was an ASCII character, the 
low byte contained the ASCII code corresponding to the 
key that was pressed. When DOS or an application wanted 
a character from the keyboard, a call to INT 16h returned 
the keycode at the head of the BIOS keyboard buffer. 

With the introduction of the AT, IBM gave us a keyboard 
with 84 keys (IBM added SysReq) and a different key 
layout. The AT keyboard produces scan codes different 
from the original PC keyboard because physical circuit 
design efficiency dictates scan code assignment by key 
location. For software compatibility, IBM provided a scan 
code translation within the keyboard controller. After this 
translation step, the scan code for a given key is identical 
to that key's scan code on a PC. Because this translation 
step happens before the BIOS gets a look at the scan code, 
the BIOS INT 9 handler (and all higher level software) sees 
the same set of scan codes as they did with the original PC. 

The latest keyboard from IBM is the 101-key enhanced 
keyboard. The most noticeable difference in the enhanced 
keyboard is the addition of a separate set of cursor control 
(duplicate editing) keys and the addition of two more func¬ 
tion keys. This keyboard has yet another key layout, and 
instead of coming up with another set of scan codes, IBM 
brought out three sets. Scan code set 1 produces scan 
codes compatible with the original PC keyboard, scan code 
set 2 produces the AT and enhanced keyboard scan codes, 
and scan code set 3 is used for the IBM RT. The active scan 
code set can be selected by software and, at boot time, 
the BIOS makes scan code set 2 the active scan code set. 


David Burki is a consultant with AGS Infor¬ 
mation Services, Inc. He specializes in systems 
and application software design and develop¬ 
ment under MS-DOS using C and assembly. You 
may contact him at AGS, 1501 L.B.J. Freeway, 
Suite 200, Dallas, TX 75234. (214) 247-8632. 
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Listing 1 (extndl6.asm) 


COMMENT ~ 


EXTND16.ASM 

This is a Terminate & Stay Resident program which when 
installed will intercept INT 16h calls and insure that 
function calls zero and one are changed to functions lOh 
and llh. 

The TSR consumes about 380 bytes when installed. 

To create an executable, assemble & link this module and 
convert the .EXE to a .COM with exe2bin. 

Author: David Burki 


END OF COMMENT 


EQUATES 


ENV OFFSET 

equ 

02ch 

GET KEY 

equ 

0 

CHK FOR KEY 

equ 

1 

X STUFF KEY 

equ 

5 

X GET KEY 

equ 

lOh 

X CHK FOR KEY 

equ 

llh 


. CODE . 

cseg segment byte public 'code' 

; — com file setup 
org lOOh 

assume cs:cseg, ds:nothing, es:nothing 
entry: 

jmp initialize 

; — storage for the int 16h vector that's intercepted 
orig_16_vect dd ? 


PRE_16() 

This function gets to look at the INT 16h function call 
and change function calls 0 & 1 to lOh & llh so that 
DOS can't destroy keycodes when it checks the status of 
the BIOS kbd buffer. 

Caution: Some programs (CEO for example) will not 
correctly interpert the keycodes returned from the 
extended keypad keys. Strange characters appear when 
these keys are pressed. 


pre_16 proc far 

; --- save the flags we received & interrupts off 
pushf 
sti 

; — if function is greater than 1 (status req) don't do 
; anything - just jump to the original vector 
cmp ah, 1 

ja go_orig_16 

; — otherwise, make function 0 into lOh & 1 into llh 
or ah,10h 

; — restore callers flags & pass on to original vector 
go_orig_16: 


popf 

jmp orig_16_vect 
pre_16 endp 

; — anything after this label is init code & will be 
; thrown away after installing 
end_re$ident label byte 


assume cs:cseg, ds:cseg, es:cseg 


FREE_ENVIRONMENT() 

Release this program's copy of the DOS environment in 
order to make this TSR as small as possible. 

Freeing the environment makes it impossible for utilities 
like MAPMEM to determine what program owns the memory 
allocated to this resident process. 

Destroys: 

AX 


free_environment proc near 
push es 

push si 

xor ax,ax 

; — get environment segment from the PSP 
mov si,ENV_OFFSET 

; — move segment addr of environment into AX & at same 
; time move the zero that's in AX into the PSP pointer 
; to the environment 
xchg ax,[si] 

or ax,ax 

jz environment_exi t 

mov es,ax 

mov ah,49h 

int 21h 

environment_exit: 

pop si 

pop es 

ret 

free_environment endp 


CK_BI0S_SUPP0RT 

Check the BIOS to see if enhanced functions are 
available by attempting to use one of the enhanced 
functions - function 5, add keycode to BIOS keyboard 
buffer. 

Returns: 

Carry clear - BIOS supports enhanced functions 
Carry set - BIOS does not support enhanced 
functions 


ck_bios_support proc near 
; — flush the BIOS kbd buffer 


mov 

ah,CHK 

F0R_KEY 

int 

16h 


jz 

buf is 

empty 

mov 

ah,GET 

KEY 

int 

16h 


jmp 

ck bios 

support 


; — once the buffer is empty, attempt to add a keycode 
; to the buffer 
buf_is_empty: 

mov ah,X_STUFF_KEY 
mov cx.Offffh 

int 16h 


TSR to Prevent Lost Keystrokes 


Page 42 — TECH Specialist 


August 1991 




















For the most part, scan code set 2 produces scan codes 
equivalent to the 84-key keyboard. The major difference be¬ 
tween the AT and enhanced keyboards is that the enhanced 
keyboard produces scan codes for the new keys. Instead of 
giving additional translation capabilities to the keyboard con¬ 
troller, INT 16h handles these new scan codes. BIOS versions 
that support the enhanced keyboard have four added func¬ 
tions in INT 16h. Three of the added functions, lOh, llh, and 
12h are the extended keyboard versions of the original INT 
16h functions 0 (get key), 1 (get key status), and 2 (get shift 
status). The other added function in INT 16h is function 5, 
which places the keycode in the CX register into the BIOS key¬ 
board buffer just as if it had been typed at the keyboard. 

When a program (including DOS) calls INT 16h with one of 
the old function values 0 or J, and the keycode at the head of 
the BIOS keyboard buffer represents one of the duplicate edit¬ 
ing keys, the BIOS graciously translates the keycode to the 
value it would have been had the corresponding editing key 
on the PC or AT keyboard been pressed. If the next available 
keycode represents a new key (F11 or FI2) or a key combina¬ 
tion not recognized by the original functions [ctrl-insert or 
numeric keypad 5 for example), INT 16h throws away the 
keycode by advancing the pointer to the head of the BIOS 
keyboard buffer. 

Generally, the translation and removal of keycodes is not a 
problem, except that DOS always uses the old function calls to 
examine or get a key. During certain functions of INT 21h, 
DOS checks the next available key in the keyboard buffer to 
see if Ctrl-C was pressed. (See “Eliminating Control-C" TECH 



Listing 1 — Cont’d 

; — if AL 

comes back non-zero add keycode failed 

or 

al ,al 

jnz 

no support 

; --- just to make sure, see if the keycode at the head 

; of the 

BIOS kbd buffer is the one we added 

mov 

ah,X CHK FOR KEY 

int 

16h 

; — is the 

buffer empty? 

jz 

no support 

; —- no, remove the keycode we stuffed with an extended 
; get-key function call 

mov 

ah,X GET KEY 

int 

16h 

; — is it 

the same keycode 

cmp 

ax.Offffh 

je 

yes_support 

; --- exit indicating no support 

no support: 


stc 


jmp 

ck bios exit 

; — exit indicating support 

yes support: 


clc 


ck bios exit 

. 
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Specialist, August 1990.) By using function 1 (get key status) to 
check the keyboard buffer, DOS causes INT 16h to remove 
the keycodes that the old I NT 16h function calls would not 
recognize. The removal or translation becomes a problem 
when, for example, your program is correctly using the BIOS 
extended keyboard function calls and does an DOS Write 
String (INT 21 h, function 9) while one of the new keycodes is 
at the head of the buffer. The keycode will not be there when 
DOS returns to your program. If your application is using these 
keycodes and uses DOS function calls, there is a high prob¬ 
ability that at least some of these keycodes will never make it 
to your program. 

The code in Listing 1 is a terminate-and-stay-resident (TSR) 
program to translate function requests that could destroy 
keycodes in the BIOS keyboard buffer. The TSR converts INT 
16h functions 0 and 1 into functions llh and 12h. This 
prevents any program (including DOS) from causing the BIOS to 
throw away buffered keycodes. Although every program 
should contain code to handle unknown keystrokes, many do 
not and may behave unexpectedly with this TSR installed. You 
will have to experiment to determine which programs will be¬ 
have properly. □ 
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Listing 1 - Cont’d 

ret 


ck_bios_support endp 


no_install_msg 

db 

'BIOS does not support extended ' 


db 

'keyboard functions.‘,0dh,0ah,'$' 

install msg 

db 

‘Installing extended BIOS key- 

board 1 

db 

1 function support.',0dh,0ah,'$' 


INITIALIZE() 

Check that enhanced BIOS keyboard support is 
available and install only if it is. 


initialize proc near 

call free_environment 
call ck_bios_support 

; — if extended BIOS kbd support not available don't 
; install 

jc no_install 

; — display the install message 

mov dx,offset installjnsg 

mov ah,9 

int 21h 

; — get the current INT 16h vector & sace it in a code 
; segment variable 

mov ax,3516h 

int 21h 

mov word ptr orig_16_vect,bx 

mov word ptr orig_16_vect+2,es 

; — put pre_16() in the vector table 

mov dx,offset pre_16 

mov ax,2516h 

int 21h 

; — calculate the length of the resident portion in 
; bytes and round up to next paragraph 

mov dx,offset end_resident 

add dx,15 

; — convert bytes to paragraphs 
mov cl, 4 

shr dx,cl 

; — terminate & stay resident, DX has the size of 
; resident portion in paragraphs 

mov ah,31h 
int 21h 

; — display the non-installation message & terminate 
; the process without staying resident 

no_install: 

mov dx,offset no_install_msg 

mov ah, 9 

int 21h 

mov ax,4c01h 

int 21h 

initialize endp 

cseg ends 

end entry 

; End of File 


August 1991 












■ TECH Preview 


45 


MultiScope Debuggers For Windows 


Comments By Ron Burk 


You have probably seen pictures of a MultiScope OS/2 
debugger, even if you don't use OS/2. The debugger’s ability to 
draw data structures graphically in a window made it very 
photogenic. After releasing an DOS version, MultiScope has an¬ 
nounced Debuggers for Windows. This article investigates the 
capabilities of this new release. 

Introduction 

The title says "Debuggers,” and not “Debugger," because 
the package includes several debuggers. MultiScope currently 
includes the DOS versions of their debuggers when you buy 
the Windows version. Since most Windows programmers also 
develop DOS programs, this strategy is probably smart. For 
both DOS and Windows, MultiScope supplies different debug¬ 
gers for different purposes. This article focuses on the Win¬ 
dows debuggers. 

The package contains post-mortem debuggers for analyz¬ 
ing programs that died of an exception or error. The actual 
dump is produced by MED, an execution monitor program that 
you start beforehand (usually by including it in your Windows 
initialization file). Once you have a dump, you can inspect the 
state of the program with the post-mortem debugger. This 
debugger is a subset of the runtime debugger; it has the same 
look and feel but does not support operations that require an 
active program (such as setting watchpoints). If you want to 
produce a dump under the broadest range of errors (and not 


MultiScope Debuggers For Windows 
MultiScope 

1235 Pear Avenue, Suite 111 
Mountain View, CA 94043 
(415) 968-4892 
FAX (415) 968-4622 


just "Unrecoverable Application Errors”), you call a special in¬ 
itialization function from your program. MultiScope also sup¬ 
plies a function you can call to force a dump. 

The problem with debugging backwards from an “Un¬ 
recoverable Application Error" (UAE) is that Windows is not a 
very secure memory manager. Since Windows essentially puts 
all Windows applications in the same virtual memory space, 
your program can do a lot of damage before Windows detects 
a problem. For example, I decided to take a working program 
and add a fatal bug in order to exercise the post-mortem 
debugger. I tried writing data on a function, writing zeroes on 
the stack segment, and not exporting my window callback 
function. These produced a variety of strange behaviors (in¬ 
cluding locking up the machine), but not a single UAE. 

The runtime debugger is the “normal" debugger, used to 
interactively debug a running Windows program. The Multi- 
Scope package also includes various remote debuggers, 
designed to move the debugging activity from the machine 
running the target programto free up memory or screen 
space. You can debug from another machine via a serial port 
or a network in real, standard, and enhanced modes. This ar¬ 
ticle focuses on the runtime debugger. 

The User Interface 

MultiScope runs as a multiple-document interface (MDI) 
Windows application. The best-known example of an MDI in¬ 
terface is the Windows Program Manager. An MDI application 
is a window containing one or more child windows, each of 
which can be moved, sized, iconized, and so on, within the 
parent window. In the case of MultiScope, each child window 
is a window into a particular debugging task, such as inspect¬ 
ing source code, viewing data structures, etc. The parent win¬ 
dow contains a main menu bar with commands that are 
global to all the child windows (such as starting or quitting a 
program). Beneath the main menu bar is a menu bar with 
commands specific to the child window you have selected. 


Ron Burk has a B.S.E.E. from the University of Kansas and has been a programmer for the post 10 years. You may contact him 
at Burk Labs, P.O. Box 3082, Redmond, WA 98073-3082. 






Figure 1 shows MultiScope in action. 
As you can see, screen space is at a 
premium when you are trying to view 
several different sources of information 
at once. Cramped as it looks, I found 
that this configuration displayed most 
everything l needed without having to 
juggle windows too much. 

The way Multiscope partitions 
debugging functions into child windows 
provides a convenient structure for 


documenting the product. Each of the 
following sections covers one of the 
MultiScope child windows, in alphabeti¬ 
cal order. 

The Assembly Window 

Rather than making you switch be¬ 
tween source code and assembly lan¬ 
guage views in the same window, 
MultiScope gives you both a source 
window and an assembly window. The 


assembly window (Figure 2) gives you 
the disassembled view of your program. 
You can set and clear breakpoints with 
the menu, keyboard, or mouse. You 
can browse in the window. Display op¬ 
tions control whether you see high- 
level language source interspersed in 
the assembly language and whether 
the disassembly uses mnemonics or 
shows the bytes that make up the op¬ 
codes. 
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The Breakpoint Window 

The breakpoint window (Figure 3) 
summarizes the breakpoints that are 
currently set in your program. The win¬ 
dow displays the location of the break¬ 
point both as an assembly-language ad¬ 
dress and in the form 

module.function: line# 

Breakpoints can have a pass count, 
which means the debugger will not 
stop at this breakpoint until the debug¬ 
ger has encountered it a specified num¬ 
ber of times. The breakpoint window 
shows both the current pass count and 
the limit. You can also specify an ex¬ 
pression with a breakpoint. Each time 
the debugger encounters the break¬ 
point, it evaluates the expression and 
stops if it evaluates to true. 

Two items not shown in Figure 3 
(they are scrolled off to the right) are 
the action field and the log string. The 
action field is an expression (in the lan¬ 
guage of the program you are debug¬ 
ging) that the debugger evaluates when 
it hits the breakpoint. The log string is 
simply text that the debugger adds to 
the log window everytime it hits the 
breakpoint. 

MultiScope also has a watchpoint 
window that shows all of the 
watchpoints you have set at any given 
time. A watchpoint is like a breakpoint 
except it stops program flow when 
specific data is accessed. For example, if 
a bug causes a certain variable to be 
set to 0 incorrectly, you can set a 
watchpoint on that variable that will 
stop the debugger when it is accessed. 
You can specify whether to stop on 
read accesses, write accesses, or both, a 
flexibility missing in most debuggers. 
Multiscope takes advantage of the 
debugging facilities of the 80386, so 
watchpoints do not slow down program 
execution. 
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The Call Window 

Figure 4 shows the call window, 
which provides a stack traceback. The 
window shows each function that is 
currently active, with the most recently 
called function at the top. Besides the 
function name, the window displays the 
name of the module it is from. Leaving 
this window displayed lets you see at a 
glance the state of your program when 
you hit a breakpoint. 

Besides providing a stack traceback, 
the call window provides an easy way 
to switch the view of other debugging 
windows, if you double-click on a func¬ 
tion in the call window, the data, 
source, and assembly windows will 
switch to viewing the source and data 
for the function you selected. You can 
also use the menus or keyboard to 
change the view of any one of those 
windows to the selected function. 

The Data Window 

You use the data window (Figure 5) 
to inspect the local and global data in 
your program. Each line in the window 
displays a different variable or element 
of a variable. The expression or set of 
variables currently displayed appears at 
the top of the window. You can also 
set watchpoints on data from this win¬ 
dow. 

Tracing through linked data struc¬ 
tures (such as trees and linked lists) is 
very easy with just the mouse and this 
window. To follow a pointer, you 
double-click on the pointer variable in 
the window. To back up a pointer chain 
you've been following, just double-click 
the right button on the expression at 
the top of the window. 

The Graphic Data Window 

The graphic data window (Figure 6) 
is the flashiest MultiScope window. To 
display data structures graphically, you 
first select a data structure in the data 
window. You then press ALT-G to dis¬ 
play it graphically in this window. Multi- 
Scope tries to follow the pointers in the 
data to construct a graph. For example, 
with a little staring, you can convince 
yourself that the data in Figure 6 con¬ 
tains a circular linked list. The window 
lets you zoom in or out, handy when 
the graph is complex. 


Figure 5 



COMPUTER 

LANGUAGE 


IJ M.HHiait'i 



presents 

C Bug # 747 


#if PROTOTYPES 

double sqrt (double); 

#else 

double sqrt (); 

#endif 

main () 

( printf ( "sqrt(S) = %g\n" , sqrt(S) ); ) 


It looks like the programmer is being careful with his prototyping, allowing 
his compiler to check his calls if it supports prototypes and allowing for the 
occasional compiler that doesn't. But, what's wrong? When does this fail? 
Call if you need a hint. 


PC-Iint will catch this and many other 
C bugs. Unlike your compiler, PC-lint 
looks across all modules of your appli¬ 
cation for bugs and inconsistencies. 

More than 270 error messages. More 
than 90 options for complete cus¬ 
tomization. Suppress error messages, 
locally or globally, by symbol name, by 
message number, by filename, etc. 

Easy to Use - If you know C you 
already know how to use PC-lint. Check 
for portability problems. Alter size of 
scalars. Adjust format of error mes¬ 
sages. Automatically generate ANSI 
prototypes for your K&R functions. 


Attn: Power users with huge programs. 

PC-lint 386 uses DOS Extender 
Technology to access the full storage 
and flat model speed of your 386. 

PC-lint 386-$239 
PC-lint DOS or OS/2 -$139 

Mainframe & Mini Programmers 

FlexeLiflt ill shrouded source 
form, is available for Unix, OS-9, 
VAX/VMS, QNX, IBM VM/MVS, 
etc. Requires only K&R C to com¬ 
pile but supports ANSI. Pricing 
starts at $798. Call for details. 




3207 Flogarth Lane, Collegeville, PA 19426 

CALL TODAY (215)584-4261 Or FAX (215)584-4266 

30 Day Money-back Guarantee. 

PA add 6% sales tax. PC-lint and FlexeLint are trademarks of Gimpel Software 
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Figure 6 
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Figure 9 



The Log Window 

The log window (Figure 7) keeps 
track of all the events that occur during 
your debugging session. This feature is 
useful for reconstructing the debugging 
steps that led to a particular state of 
the program. The window displays the 
last 100 entries, though you can send 
all the log entries to a file. 

The Memory Window 

The traditional debugging activity of 
"dumping" takes place in the memory 
window (Figure 8). If you select a data 
item in the data window and then 
press ALT-E, the memory window will 
display a dump of the data. You can 
dump in a variety of formats: character, 
text, byte, word, unsigned, integer, long 
integer, short real, long real, extended 
real, or address. You can also set data 
watchpoints from the memory window 
and modify memory locations directly. 

One interesting feature of the 
memory window is the “live memory 
expression." You can enter an expres¬ 
sion that evaluates to a memory ad¬ 
dress and associate the expression with 
the memory window. Then, each time 
the debugger stops at a breakpoint, it 
evaluates the expression and changes 
the memory window dump to that ad¬ 
dress. This can save a lot of thumbing 
through memory, if you can come up 
with the right expression for what you 
are doing. 

The Module Window 

The module window (Figure 9) lists 
the names of the object modules that 
make up your program. To the left of 
each module name is status informa¬ 
tion. for each module that contins a 
breakpoint, the first column contains an 
asterisk (*). If you are currently stopped 
at a breakpoint in that module, a 
pound sign (#) appears instead. A 
greater-than sign (>) in column two indi¬ 
cates that some procedure in the 
module is in the current call tree. If, on 
the other hand, the module has not 
even been loaded, a v will appear. 
Finally, column three contains a + for 
each module with trace enabled. In 
other words, if, while single-stepping 
through code, you arrive at a call to a 
function in another module, the debug¬ 
ger will step into that module if it is 
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Figure 10 



Figure 11 



Figure 12 
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marked with a + and over the call if it 
is not. 

Just as with the call window, you 
can use the mouse, menu, or keyboard 
to alter other windows (source, assemb¬ 
ly, and data windows) to view a specific 
module. This window also serves to lo¬ 
cate the module in which a particular 
procedure resides. 

The Procedure Window 

The procedure window (Figure 10) 
basically provides an inverted view of 
the information in the module window. 
Here, each procedure appears on a 
separate line, along with the module in 
which it appears, its address, and 
whether it is a near or far procedure. 
Again, you can use the mouse, key¬ 
board or menus to alter the source, as¬ 
sembly, or data windows to view a 
specific procedure. 


The Register Window 

A view of the current state of the 
CPU registers appears in the register 
window (Figure 11). You can display the 
registers in either decimal or hex for¬ 
mats and alter a register by selecting it 
with the mouse and pressing ALT-M. In 
one of the few obtuse parts of the user 
interface, this window also has a menu 
that allows you to do byte or word port 
I/O. If you need to output a byte, you 
won’t intuitively select the register win¬ 
dow, you just have to know it's there. 

The Source Window 

This window (Figure 12, which also 
appeared in Figure 1) is the center of 
most debugging. It displays the source 
code of the program you are debug¬ 
ging. You can view source in any file, 
search for text or line numbers, and set 


DOS 

Documented 


Microsoft 

MS-DOS 

Programmer’s Reference 



Updated to 
MS-DOS version 5! 

The Microsoft guide to MS-DOS'* 
internals is back. This exclusive guide is 
now updated to include all versions of DOS 
from 3.3 through 5.0. This is the DOS 
book that gets used! Now available 
wherever computer books are sold. 

Or order directly from Microsoft Press. 

$24.95 

To place your credit card order, call 

1-800-MSPRESS. 

8am to 5pm Central Time. 

Refer to ad AHG. 


Microsoft 

V K K S S 


The Authorized Editions 

Microsoft Press, One Microsoft Way, 
Redmond, WA 98052-6399. 

$32.95 in Canada. 

Call Macmillan Canada.416-293-8141. 
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if (U == Microsoft® ISV 
&& U.GUI == Windows™(3) 

&& (U.SDK || U.MDK || U.DDK) 
&& U.VAL > MinWages) 


Softelligence™ libraries 
minimize the time spent 
porting DOS programs or 
developing new apps for 
Windows 3. Maximize 
your power using the 
libraries optimized for 
the new multimedia & 
desktop publishing 

standards: 

"More Power To You!"™ lets you control 
Windows 3 at the DPMI (DOS Protected Mode 
Interface) level. Instantly access video & other 
hardware for animation, arcade-style games, & 
real-time processing. You decide when to 
control hardware, & when to let the GDI control 
it. DOS graphics run with minimum 
modifications, & much faster than GDI 
graphics. 

"More Memory For You!"™ gives you the 
quickest possible port from the DOS c/malloc 
functions, & a fast virtual memory allocator for 
small & medium memory models. Also 
includes many ''lstr/lmem" functions missing 
from the SDK. 

Animagic 256™ reads & simultaneously 
displays &/or animates &/or color-cycles 
multiple multimedia standard 256-color 320 x 
200 GIF™ &/or Animator™ FLI files. Requires 
"More Power To You!" described above. 

Bezier Master™ is believed to be the fastest 
software implementation for bezier curve 
display, invented at Softelligence, using only 
16-bit integers & no multiplies or divides! 
Bezier curves are the most important curves 
today; PostScript™ is completely based on 
them. 

Type Master™ reads, decrypts & decodes 
Adobe™ Type 1 PostScript fonts, stores all data 
including subroutines and hints, & even 
translates to a Type 3 font. Reads the hundreds 
of commercial PostScript fonts blazingly fast! 
Includes functions to display font outlines that 
interface to Bezier Master. 

Call Softelligence, (800)446-8088, or FAX, 
(206)284-3898. $395 per library. Multi¬ 

product discounts & source code available. 
MC/Visa accepted. No royalties. 

(C)1991 Softelligence, 3213 W Wheeler St, Suite 140, 
Seattle WA 98199. Microsoft is a registered 
trademark & Windows is a trademark of Microsoft 
Corp. "More Power To You!", "More Memory For 
You!", Animagic 256, Bezier Master & Type Master 
are trademarks of Softelligence. All other trademarks 
are trademarks of their respective companies. 
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and clear breakpoints. You can also up¬ 
date the assembly window from here 
to display the same routine in assembly 
language. 

One of the most common debugging 
tasks is executing to a certain spot in 
the program. With the source window, 
you just double-click on a source line 
and Multiscope sets a breakpoint there 
and executes to that point. This is con¬ 
venient when you are doing initial, ex¬ 
ploratory debugging. It is worth noting 
that this window (like all of them) 
scrolls dynamically. That is, the source 
slides quickly up and down in the win¬ 
dow as you thumb the scroll bar. In 
some software, the windows are not 
updated until you release the scroll bar, 
making it difficult to browse to the spot 
you want. 

The Spy Window 

This window gives you a superset of 
the capabilities of the Microsoft Win¬ 
dows SDK Spy utility. The spy window 
in MultiScope logs any Windows mes¬ 
sages that you want to monitor. You 
select classes of messages (like mouse 
or window messages) or specific mes¬ 
sage numbers that you are interested 
in. A dialog box lets you select any win¬ 
dow or windows on the screen to spy 
on. You can also manually post mes¬ 
sages to a particular window. One 
menu selection turns on “IParam 
Memory,” so that every time a message 
is logged, MultiScope uses the long 
parameter as a memory address and 
displays a dump of the memory at that 
address in the memory window. 

Version 1.01 of the Multiscope run¬ 
time Windows debugger contains some 
new features in the Spy window. You 
can now set breakpoints on messages 
that the Spy window is spying on. You 
just select the window and message 
that you are interested in and the Spy 
window sets a breakpoint at the entry 
point of the correct window procedure 
that only breaks when the desired 
message arrives. This automates the 
common debugging task of setting a 
breakpoint with a conditional expres¬ 
sion that checks the message number. 

Summary 

If you have experience using Win¬ 
dows and any other modern PC debug¬ 
ger, you will have no trouble using 
MultiScope. I read enough of the 



Microsoft 

WINDOWS 

VfciMi m 311 Ci «nputiNc Pn Ou .1 


manual to install the debuggers and 
then used the debugger for about a 
week before looking at the manual 
again. I felt I had mastered the product 
after only about an hour of experimen¬ 
tation. The online help is pretty much 
the same as the manual and doesn't 
contain any hyper-text features like 
cross referencing. On the other hand, 
most commands are fairly obvious from 
glancing at the menus. 

Even though the debuggers available 
from many compiler vendors are quite 
good, MultiScope is a step beyond 
them. If you have to spend many 
waking hours staring at a debugger, 
you should go to your local software 
store and give MultiScope a test run, 
just to see what the state of the art 
looks like. □ 
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TECH Tips 



Leor Zolman 


Please send us your best 
tricks and hacks — those 
c/ever pieces of code to 
make things work the 
wag they should! You'll 
receive at least $50 for 
each tip that we print 

Send gour submissions to.- 
TECH Tips 
Leor Zolman 
2601 Iowa 
Lawrence, KS 66046 


A Data Dictionary Alternative 


Nick Makris - 415/647-1193 
STARTECH SYSTEMS 
12 Longview Court 
San Francisco, CA 94131 

Have you ever needed to determine the presence of a particular string of text 
within any one or (perish the thought) all of your source code files? 

While some programmers have the luxury of a data dictionary, most of us are 
relying on a text search program of some kind. Even with a data dictionary, it is not 
always up to date (who has the time?), but more importantly, they invariably don't 
track what you are looking for. 

As many of you, I have relied on the use of the Norton Utilities (v4.0) text search 
program ( TS). I redirect the output of TS to a log file using the DOS redirect option 
and the TS /log option. However, managing that output can become difficult when 
there are a large number of appearances and the resulting file is cluttered with the 
code around each appearance. 

Listing 1, FINDTEXT.PRG, shows the dBase IV code necessary to create a con¬ 
densed and manageable listing that may then be processed by any word processor. 
I usually print it and use the resulting page as a check list while performing the 
necessary program changes. 

Figure 1 shows the results of a find of the string 'ans' when running FINDTEXT 
against the TS output from source code file FINDTEXT.PRG. There are two steps in 
the process: 



Leor Zolman bought his /irst microcomputer (an IMSAI 8080) while in high school in LA., 
carried it to MIT., withdrew, and wrote the BDS C compiler with it in assembly language. 
That was enough assembly language hacking to last a lifetime, so now he enjoys 
UNIX/Xenix system administration, article writing, and raising his newborn daughter 
Kate/yn. You can reach him at leor@rdpub.com or uunet!bdsoft!rdpub!leor. 


















Figure 1 

Searching contents of files 

Searching F:\TNC\SUBMIT\findtext.prg 
Found at line 19, file offset 942 

Found at line 22, file offset 1,097 

Found at line 24, file offset 1,108 

Found at line 24, file offset 1,123 

Found at line 25, file offset 1,137 

Found at line 28, file offset 1,206 

Found at line 30, file offset 1,243 

Found at line 32, file offset 1,320 

Found at line 33, file offset 1,383 

Found at line 35, file offset 1,459 

Found at line 38, file offset 1,501 

11 occurrences of the text "ANS" 


1) The syntax for creating the input file to the FI NDTEXT 
program is 


erased at the end of the program, you could use that data to 
programatically prompt a programmer for changes across an 
entire PRG universe. This would entail converting each affected 
source file to a database, prompting for changes to each 
record noted, converting the changed file back to an ASCII file 
and perhaps recompiling the program. I wouldn't recommend 
making the changes themselves programatically because text 
searches invariably produce just what you weren't expecting. 
In any case, good luck. 



A Printf()-Uke Function 
With Attribute Control 

Robert A. Radcliffe 
Computer Application Engineers, Inc. 

517 North 19th Street 
Philadelphia, PA 19130 


TS FINDTEXT.PRG 'ans' /LOG > ANS.TXT 

You could run this from the dot prompt if it suits your purpose. 

2) Then from the dot prompt or from RUNTIME or via your 
favorite database program, enter DO FINDTEXT. Enter the 
filename to use as ANS. TXT - the output file will be called 
ANS.OUT which is easily processed from any word processor. 
While this program is written in dBase and is demonstrated 
with dBase source code, any flavor of text file could be 
reviewed in this manner. 

The FINDTEXT program's usefulness doesn’t end there. If 
you were to save the resulting LOGTEXT.DBF file, which is 


The lack of an attribute-sensitive version of the printfO 
family of C runtime functions is overcome by the function 
aprintf (see Listing 2). With aprintf, an initial argument is 
provided that controls color, blinking, reverse video, and in¬ 
visibility if necessary. 

This custom, variable-argument function uses the va_start 
macro to establish a pointer to the variable arguments (...) that 
are present. It then calls runtime function vsprintf to convert 
the arguments according to the standard formatting rules 
specified by the format parameter. The resulting output text 
is placed into buffer. 


Windows 3.0 


Call For Papers 


We are currently seeking articles related to Windows 
limited to: 

• Communicating with DOS applications 

• Using the sound generation functions 

• Working with initialization files 

• Doing your own multi-threading 

• C++classes for Windows 

• Using the clipboard 

• Using the communications functions 

If you are interested in writing about one of these tc 
editorial staff for author guidelines at (913) 841-1631. 


3.0 development. Potential topics include, but are not 

• Internationalization issues for Windows 
programs 

• Debugging Windows C++ programs 

• Managing color in your Windows application 

• Porting a DOS user interface to Windows 

• C/C++development utilities 

• C++ memory management under Windows 

or you have a related idea, please contact our 


TECH. .. _ 
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Listing 1 


★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★A** 

* ★ 

* Author - Nick Makris - STARTECH SYSTEMS - San Francisco, CA * 

* Date - DECEMBER 1989 * 

* ★ 

* *********** FImd text program ************ * 

* * 


*********** 


RELEASED TO THE PUBLIC DOMAIN 


************ 


****************************************************************************** 


* This program works in conjunction with the Norton Utilities 4.0, Text Search 

* (TS) program. Use syntax TS *.PRG '<text to find>' /LOG > <output filename* 

* This program analyzes the resulting file looking for line number references 

* and deletes all other associated lines. The resulting text file contains 

* only those lines which point to a specific file and line number which 

* may then be printed and used for any intended purpose. 


SET DELETED OFF 

ANS = SPACE(12) && ASSUMES FILE IS IN DEFAULT DIRECTORY 

@15,16 CLEAR TO 17,63 
@15,16 TO 17,63 DOUBLE 

@16,18 SAY "ENTER THE FILE NAME TO ANALYZE " GET ANS 
READ 

ANS=TRIM(LTRIM(ANS)) 

IF LEN(ANS)=0 .OR. READKEY()=12 && USER WANTS OUT 
RETURN 
ENDIF 

X=AT('. 1 ,ANS) 

IF X # 0 

OUTFILNAME = SUBSTR(ANS,1,X-1)+ 1 .OUT 1 

ELSE && USER DIDN'T INCLUDE AN EXTENSION NAME 

IF LEN(ANS) <9 && AND THE NUMBER OF CHARS IS NORMAL 

OUTFILNAME = ANS+'.OUT' 

ELSE && ABNORMAL LENGTH OF FILE NAME 

OUTFILNAME = SUBSTR(ANS,1,8)+'.OUT' 

ENDIF 

ENDIF 

FILNAME = ANS 

IF .NOT. FILEC'&FILNAME") 

@15,22 CLEAR TO 18,58 
@15,22 TO 18,58 DOUBLE 

@16,24 SAY “UNABLE TO FIND FILE "+FILNAME+"!" 

@17,24 SAY "Press any key to continue!' 1 
zi = 0 

DO WHILE zi = 0 
zi = INKEY(1) 

ENDDO 

RETURN 

ENDIF 

USE SCREELIN && A SINGLE FIELD (SCRNLINE) DATABASE - DEFINED AS 80 CHARS 
COPY STRU TO logtxt 
USE logtxt 

APPEND FROM &FILNAME SDF && IMPORT THE NORTON TS OUTPUT 

SVLINE=" " 

GO TOP 

DO WHILE .NOT. EOF() 

IF .NOT. 'Searching' $ SCRNLINE .AND. .NOT. 'Found' $ SCRNLINE 
DELETE 
ENDIF 

IF 'Searching' $ SCRNLINE && RETAIN ONLY ONE REFERENCE TO EACH FILE 
IF SVLINE=SCRNLINE && MULTIPLE APPEARANCES IN THE SAME FILE 

DELETE 

ELSE && NEW FILE BEING CHECKED 

SKIP -1 

RECALL && PROVIDES A BLANK LINE FOR REFERENCE 

SKIP 
ENDIF 

SVLINE=SCRNLINE 

ENDIF 



COMMUNICATION 
PROBLEMS GOT 


h^Jow you can analyze and diag¬ 
nose stubborn serial communication 
problems in real time using your PC or 
compatible computer and serial ports. 

The INTERCEPTOR allows you to exam¬ 
ine and monitor serial communications at 
up to 115,200 baud while displaying 
the state of all signals. 

Monitor data transmitted between 
two serial devices visually, or capture 
serial data to your floppy or hard drive 
for detailed examination with The 
INTERCEPTOR'S online editor. Multiple 
configuration files allow you to easily 
interface devices with different baud 
rates and communication parameters. 

While the INTERCEPTOR'S multitask¬ 
ing capabilities maintain time critical 
data communication streams at high 
speed, you can independently set stan¬ 
dard and non-standard baud rates, word 
size, parity, stop bits, line break duration, 
and determine DTR/DSR and RTS/CTS 
hardware handshaking support at any 
time during program operation. 

The online editor makes it easy to 
load, save, or enter strings of data in 
hex or ASCII format to transmit to either 
serial port, for use in pattern searching or 
to examine captured data files. Fast and 
efficient disk save routines allow captur¬ 
ing large data transmissions at nigh 
baud rates for examination with the 
online file viewer. 

The INTERCEPTOR also supports a 
non-invasive datalogging monitor mode 
and is simply the fastest serial diagnostic 
program on the market, backed up by 
db Technology's 30-day money back 
guarantee. 

1 - 800 - 262-2681 

Call today and order your copy of 
The INTERCEPTOR (VISA/MC accept¬ 
ed) or send $119 (US) (Foreign orders 
add $10 shipping) to: 

db Technology 

P.O. Box 40299 
Tuscaloosa, AL 35404 
(205)556-9020 
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Listing 1 - Cont’d 


IF 'occurred'$ SCRNLINE 
RECALL 
SKIP -I 

RECALL && PROVIDES A BLANK LINE FOR REFERENCE 

SKIP 
ENDIF 
SKIP 
ENDDO 

IF FILE("&OUTFILNAME") 

ERASE &OUTFILNAME 
ENDIF 

COPY TO &OUTFILNAME SDF FOR .NOT. DELETED() 

&& COPIES FILE TO ”<input filename>.OUT“ 

USE 

ERASE logtxt.dbf && ERASES TEMPORARY DBF CREATED WITH COPY STRU 

RETURN 

* End of File * 


Listing 2 

/* = = = = = = = = = =: = = =: = = = = = = = = = = = = = = = = = S tart = = = = = = = = = = = = = = = = = = = = = = = = = = = = == = = = = */ 


/* aprintf(): printf()-like function that provides attribute control;*/ 
/* useful for both mono and color monitors in textmode; provides for */ 
/* visibility, underscore, reverse video, blinking, intensity and */ 
/* color control; requires DEVICE=ANSI.SYS in CONFIG.SYS; suitable */ 
/* for use with any Microsoft (MSC) or Borland (BC) C compiler, */ 
/* and for any memory model (T,S,M,C,L,H); software adapted from the */ 
/* book ENCYCLOPEDIA C, by R.Radcliffe (Sybex/1991), Pg 951-952. */ 

#include <stdarg.h> /* va_list, va_start() */ 
#include <stdio.h> /* printf(), scanfQ, vsprintf() */ 
#include <string.h> /* strcat(), strcpyO, strlen() */ 

/*-custom prototypes-*/ 

int aprintf(unsigned char, const char *, ...); 


/*-helpful defined items/ perhaps create a header file-*/ 


#define BLINKON 0x80u 

#define BACK_BLACK OxOOu 
#define BACKJLUE OxlOu 
#define BACKJ3REEN 0x20u 
#define BACK_CYAN 0x30u 
Idefine BACK_RED 0x40u 
Idefine BACK_MAGENTA 0x50u 
#define BACK_YELL0W 0x60u 
Idefine BACK_WHITE 0x70u 

Idefine BOLDON 0x08u 

Idefine FOREJLACK OxOOu 
Idefine FORE_BLUE 0x01u 
Idefine FORE_GREEN 0x02u 
Idefine F0RE_CYAN 0x03u 
Idefine F0RE_RED 0x04u 
Idefine FORE_MAGENTA 0x05u 
Idefine F0RE_YELL0W 0x06u 
Idefine FORE_WHITE 0x07u 

Idefine INVISIBLE OxOOu 
Idefine UNDERLINE OxOlu 
Idefine NORMAL 0x07u 
Idefine REVERSE 0x70u 

lif (0) /* begin comments by preprocessor */ 
/*-attribute byte details-*/ 


To create the attribute byte, bit-wise OR together a desired effect 
from each of the following categories: (1) Blinking Control, 

(2) Background Color, (3) Intensity Control and (4) Foreground Color 


Then, 80x86 interrupts are generated 
to establish the video attribute control for 
the subsequent display using runtime 
function printf. Upon completion, the 
original video attribute setting is restored. 

Variations of this routine can ac¬ 
comodate other available DOS/BIOS in¬ 
terrupts. 

The sample main program 
demonstrates how aprintf is called, 
and how the attribute byte can be 
input in hexadecimal format. Enter 0 to 
terminate the program. 

Due to difficulties generalizing 
aprintf for both environments where 
the standard ANSI.SYS device driver is 
installed and environments where 
ANSI. SYS is not installed, I decided to 
code aprintf so that it would only 
work in conjunction with the presence 
of ANSI.SYS - a common CONFIG.SYS 
choice. Therefore I have chosen to ex¬ 
ploit the use of ANSI.SYS escape se¬ 
quences (beginning with OxlB). This 
software should work fine for any DOS C 
compiler if ANSI.SYS is installed; I have 
tested aprintf successfully with both the 
Microsoft and Borland C compilers. 



Random Number 
Generation 

Jesse Chisholm 
137 East Fremont Avenue, #49 
Sunnyvale, California 
U.S.A. 94087-2501 


I have seen many applications that 
need random numbers and call the 
compiler's built-in random number gen¬ 
erator. That's fine and it is good that 
compiler writers have a random num¬ 
ber routine in their library. Unfortunate¬ 
ly, compiler writers have the habit of 
using a form of random number gener¬ 
ator that is easy to implement, but is 
not very good at its job. 

For example, the Microsoft C v5.1 
library has the routines srand(seed) 
and rand() (Listing 3 shows decompiled 
versions of these routines). For simple 
applications, these numbers may well 
be fine. rand() returns numbers in the 
range 0..32767 and a period of 2 30 if 
your initial seed is odd, shorter if it is 
even. One of the algorithm's drawbacks 
is that it takes advantage of the over¬ 
flow in an unsigned long multiply to 
simulate a modulo by 2 32 . 
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Listing 2 —Cont’d 

For Example: 

(1) (2) (3) (4) 

attribute = BLINKON | BACK_BLACK | BOLDON | FORE_WHITE 
attribute = 0x80 j 0x00 j 0x08 j 0x07 

attribute ==> 0x8F 


Attribute Byte Bit Settings 


bit-7 Blink Control 

bit-6 Background Red-gun 

bit-5 Background Green-gun 

bit-4 Background Blue-gun 


(0=0FF, 1=0N) 
(0=0FF, 1=0N) 
(0=0FF, 1=0N) 
(0=0FF, 1=0N) 


bit-3 Intensity Control (0=L0W, 1=HI) 
bit-2 Foreground Red-gun (0=0FF, 1=0N) 
bit-1 Foreground Green-gun (0=0FF, 1=0N) 


bit-0 

Foreground Blue-gun 

(0=0FF, 

1=0N) 


RGB (Red:Green:Blue) 

Red:Green:Blue Color 

Bit— 
Bits 

Settings 

Decimal 

SGR 

Back 

SGR 

Fore 

OFF: 

OFF: OFF 

BLACK 

[000] 

0 

“40“ 

"30" 

OFF: 

OFF: ON 

BLUE 

[001] 

1 

"44" 

"34" 

OFF: 

ON : OFF 

GREEN 

[010] 

2 

“42“ 

"32" 

OFF: 

ON : ON 

CYAN 

ron] 

3 

"46" 

"36" 

ON: 

OFF: OFF 

RED 

[100] 

4 

"41" 

"31" 

ON: 

OFF: ON 

MAGENTA 

[101] 

5 

“45" 

"35" 

ON: 

ON : OFF 

YELLOW 

rnoi 

6 

"43" 

"33" 

ON: 

ON : ON 

WHITE 

mi] 

7 

"47" 

"37" 


Typical Attribute Byte Settings 


0x00 non-display (invisible) 

0x01 underline (monochrome only) 

0x07 normal display (white on black) 

0x70 reverse video (black on white) 

0x87 blinking normal display 

OxFO blinking normal reverse video display 


#endif /* end preprocessor comments */ 

/*-function aprintf()-*/ 

int aprintf( unsigned char attr, const char ‘format, ... ) 

( 

int size; /* string length */ 

int ret; /* aprintf() return count */ 

vajlist ptr; /* va_start() address */ 

char buffer[0x80]; /* workspace for attr + string */ 

/* ansi.sys SGR (Set Graphics Rendition) Control Sequences */ 

/* bold/ underscore/ blink/ reverse/ invisible */ 

static const char ‘control[] = 

( *1;*, "4;", "5;", "7;”, ”8;" }; 

/* see SGR Back Table above */ 

static const char *back[] » 

{ "40;", "44;", “42;", "46;", "41;", "45;", “43;", "47;" ); 

/* see SGR Fore Table above */ 

static const char ‘fore[] = 

{ “30;", "34;", "32;", "36;", "31;", “35;", ”33;", "37;" ); 

/* start graphics rendition prologue */ 

strcpy(buffer,"\xlb[?71\xlb[0;“); /* no line wrap; reset attr */ 

/* test/set blinking attribute bit */ 

if (attr » 7) strcat(buffer, control[2]); 

/* test/set background color attribute bits */ 

strcat(buffer, back[(unsigned char)(attr « 1) » 5]); 

/* test/set intensity attribute bit */ 

if ((unsigned char)(attr « 4) » 7) strcat(buffer, control[0]); 

/* test/set foreground color attribute bits */ 

strcat(buffer, fore[(unsigned char)(attr « 5) » 5]); 
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Listing 2 — Cont’d 


/* test special attribute bit cases 


*/ 

/* --> invisible criteria 

if ( ((unsigned char)(attr « 1) 

» 5) 

== (BACK BLACK » 4) && 

*/ 

((unsigned char)(attr « 5) 
strcat(buffer, control[4]); 

>> 5) 

== F0RE_BLACK ) 


/» --> underline criteria 



*/ 

if ( ((unsigned char)(attr « 5) 

» 5) 

== UNDERLINE ) 


strcat(buffer, control[1]); 




/* --> reverse video criteria 



*/ 

if ( ((unsigned char)(attr « 1) 

» 5) 

== (BACK WHITE >> 4) && 


((unsigned char)(attr « 5) 
strcat(buffer, control[3]); 

» 5) 

== F0RE_BLACK ) 


size » strlen(buffer); 

/* 

overwrite very last semi-colon 

*/ 

strcpy(&buffer[size-l], “m"); 
size » strlen(buffer) ; 

/* 

end graphics rendition prologue 

*/ 

va start(ptr, format); 

/* 

format variable to buffer 

*/ 

ret = vsprintf(&buffer[size], format, ptr); 


strcat(buffer, "\xlb[0m\xlb[K") ; 

/* 

reset attr; blank to EOL 

*/ 

printf(buffer) ; 

/* 

display attr control & text 

*/ 

fflush(stdout); 

/* 

flush output buffer 

*/ 

return (ret); 

/* 

count of characters displayed 

*/ 

) 

/* 

end function aprintf() 

*/ 

/* -embedded 

test driver main()- 

-*/ 

#if Idefined(NDEBUG) 

/* 

conditional compilation 

*/ 

int main( void) 

/* 

embedded test driver main() 

*/ 

\ 

int retval; 

/* 

aprintf() count of characters 

*/ 

unsigned char attr; 
while (1) ( 

/* 

attribute control byte 

*/ 

aprintf(NORMAL|B0LD0N,"\nEnter Attribute as Oxhh (0x00 to END): ") 


fflush(stdin); 

/* 

clear the input buffer 

*/ 

scanf("%x", &attr); 

/* 

get attribute from user 

*/ 

if (lattr) break; 

/* 

test to end 

*/ 

retval = aprintf(attr, "%d %f %s". 

33, -100.25F, "Sample String!") 


aprintf(NORMAL, "\nCharacters written = %d", retval); 


/ 

aprintf(INVISIBLE, "\nYou will not see 

this message\n“); 



/* 

end function main() 

*/ 

#endif 

.... 

=stop= 


■-*/ 


Listing 3 

/* 

Random number generator used by the standard 
library for the Microsoft C compiler version 5.1. 

*/ 

static unsigned long seed; 

void srand(int iseed) 

{ 

seed « (unsigned long) iseed « 16; 

) 

int rand() 

( 

/* 

** incidental mod of 2^32 by ignoring 
** overflow during multiply and add 
*/ 

seed = seed * 2140131 + 2531011L; 
return ((seed » 16) & 0x7FFF); 

) 

/* End of File */ 


Over the years, a great deal of re¬ 
search has been done on random num¬ 
ber generation, much of it published in 
the Communications of the ACM. In the 
October 1988 issue, Stephen K. Park and 
Keith W. Miller recommend a minimal 
standard for random number genera¬ 
tion. They explain the math theory be¬ 
hind choosing an appropriate root for 
the prime number and they give an al¬ 
gorithm that is portable and remains 
within the confines of 32-bit arithmetic. 

Listing 4 shows my implementation 
of their algorithm. It has a range of 
1..2147483646 and a period of 
2147383646 before returning to the ini¬ 
tial seed. You can check that you have 
the routines implemented correctly if 
you start it off with the seed = 1L and 
check to see if the 10001st seed is 
1043618065L. 

Listing 5 shows some simple ways of 
converting this large number into 
uniform or normal random numbers in 
whatever range you need. 

In the October 1990 issue of CACM, 
Pierre L’Ecuyer goes into further details 
about random number generators used 
in simulations. Listing 6 gives an im¬ 
plementation of a generator they sug¬ 
gest that has a range of 0..2 32 - 1 and a 
period of about 2 61 before the se¬ 
quence repeats. 

If your system only has 16-bit arith¬ 
metic, you can still use this technique 
With PRIME1=32749, R00T1=182, 

QU0T1=179, REMN1=171, and 

PRIME2=32719 R00T2=175 QU0T2=186 
REMN2=169 and combining bits 14..7 of 
each seed to get a number in the range 
-32768..32767 and a period of 
1071514531 before sequence repeat. 
Using these numbers, all intermediate 
arithmatic will remain with the signed 
16-bit range. 

As submitted, Mr. Chisolm's code 
ran only under Microsft C v5.1 due to 
a reliance on the Idiv function and 
ldiv_t type definition. To support 
other environments, I have written 
definitions for Idiv and ldiv_t, and in¬ 
cluded them in Listings 4 and 6. Note 
that these elements rely on the ability 
to return structures from a function 
call; if you are using a compiler that 
does not support this feature, you will 
need to re-write the code to pass the 
information in some other manner, 
such as via structure pointers instead 
of actual structures. □ 
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Listing 4 


Listing 5 

/* 


/* 

* Minimal Standard Random Number Generator recommended 


* Some simple routines to map the minimal standard 

* by S.K. Park and K.W. Miller. (CACM October, 1988). 


* random number generator into ranges and distributions 

*/ 


* of your choice. 

*/ 

static long seed; 


#define PRIME 2147483647L /* 2*31 - 1 */ 


/* 

* urand(): returns uniformly distributed 

Idefine ROOT 16807L 


* integers in the range 1o..hi 

#define QUOT 127773L /* PRIME DIV ROOT */ 


*/ 

#define REMN 2836L /* PRIME MOD ROOT */ 



/* 


int urand(int lo, int hi) 

{ 

* Define type ldiv t, function 1 div() to match 


long tmp; 

* Microsoft C 5.1 library: 



*/ 


tmp = stdrand(); 

typedef struct { 


return((int)(tmp * (long)(hi - lo) + (long)lo)); 

) 

long quot; 



long rem; 


/* 

) ldiv t; 


* nrand(): returns normally distributed 



* integers in the range 1o. .hi 

ldiv t ldiv(long int numer, long int denom) 


*/ 

\ 

1div_t temp; 


int nrand(int lo, int hi) 

/ 

temp.quot * numer / denom; 


long tmp; 

temp.rem = numer % denom; 


int i; 

return temp; 



i 


for(tmp=0, i=0; i<4; i++) { 

/* 


tmp += urand(lo,hi); 

1 

** sets initial seed, ensuring that it is never 0 

*/ 

void stdsrand(long lseed) 

/ 


tmp * (tmp + 2L) / 4L; 


return((int) tmp); 

) 

l 

extern long time(); 


/* 

seed = lseed & 0x7FFFFFFF; 


* furandQ: 

* returns uniform random numbers in the 

while (seed == OL) { 


* range 0.0 to 1.0 (exclusive) 

seed = time((long *) 0) % PRIME; 


*/ 

/ 

} 


float furand() 

/* 


return(stdrand() / 2147483647.0); 

** returns uniformly distributed long integers 


i 

** in the range 1..2147483646 



*/ 


/* 

long stdrand() 


* returns normal random numbers in the 

* range 0.0 to 1.0 (exclusive) 

( 


*/ 

ldiv t temp; 



long test; 


float fnrand() 

/ 

if (seed *» OL) 


i 

float tmp; 

stdsrand(OL); 


int i; 

temp = ldiv(seed, QUOT); 


for(tmp=0.0, i=0; i<4; i++) ( 

test = ROOT * temp.rem - REMN * temp.quot; 


tmp += furand(); 

\ 

if (test > OL) ( 


return(tmp / 4.0); 

seed = test; 


I 

) else { 



seed * test + PRIME; 

) 


/* End of File */ 

return (seed); 

) 

/* End of File */ 
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Listing 6 


/* 

An extension of the minimal standard that 
increases the Length of the sequence from 
(2"31 - 2) to about (2^62). 

*/ 


static long seedl; 
static long seed2; 




#define PRIME1 

2147483563L 




#define R00T1 

40014L 




#define QU0T1 

53668L 

/* PRIME1 

/ R00T1 

*/ 

#define REMN1 

12211L 

/* PRIME1 

% R00T1 

*/ 

#define PRIME2 

2147483399L 




#define R00T2 

40692L 




#define QU0T2 

52774L 

/* PRIME2 

/ R00T2 

*/ 

#define REMN2 

3791L 

/* PRIME2 

% ROOT2 

*/ 

/* 

* Define type 

ldiv t, function 

1 div () to 

match 


* Microsoft C 

5.1 library: 





*/ 

typedef struct { 
long quot; 
long rem; 

} ldiv_t; 




INTEL® 80486 III 

* MACRO! DISASSEMBLER 

MD86 (Masterful Disassembler) is the 
most comprehensive macro disassembler 
on the market. Interactive by design not 
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► Command menus and help screens 
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► COM/EXE/SYS/memory/other^-. 
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Still only $67.50 + tax ($1.50 s/h) 

C.C.SOFTWARE (TlyJ 
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1div_t 1div(1ong int numer, long int denom) 

{ 

1div_t temp; 

temp.quot = numer / denom; 
temp.rem = numer % denom; 
return temp; 

} 

void extsrand(long lseedl, long lseed2) 

{ 

extern long time(); 

seedl = lseedl & 0x7FFFFFFF; 
seed2 = lseed2 & 0x7FFFFFFF; 
while ( (seedl == OL) || (seed2 == OL) ) { 
seedl = time((long*)0) % PRIME1; 
seed2 = time((long*)0) % PRIME2; 

} 

} 

long extrand() 

{ 

1div_t temp; 
long test; 

if ((seedl == OL) || (seed2 == OL)) 
extsrand(OL, OL); 

temp = ldiv(seedl, QU0T1); 

test = R00T1 * temp.rem - REMN1 * temp.quot; 

if (test > OL) { 

seedl = test; 

} else { 

seedl = test + PRIME1; 

} 

temp = ldiv(seed2, QU0T1); 

test = R00T2 * temp.rem - REMN2 * temp.quot; 

if (test > OL) { 

seed2 = test; 

} else { 

seed2 = test + PRIME2; 

) 

/* mask seedl with OxFFFFOOOO for full 

range */ 

return(((seedl < 1) & 0x7FFF0000) 

| ((seed2 > 14) & OxOOOOFFFF)); 

} 

/* End of File */ 
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Data Desk 



Using VIEWs In Programs 


Tables in SQL come in several flavors. A base table is a materialized table that is 
part of the database schema and that is persistent between sessions. A temporary 
table is a materialized table that is not persistent between sessions. A VIEW table is 
a virtual table which is persistent between sessions. Officially, the implementor 
decides whether or not to materialize it. 

Every version of SQL has base tables. A few versions of SQL have temporary 
tables, or at least allow users to create private tables for their own work. Every 
version of SQL has views, but they behave somewhat differently from product to 
product. 

A view is created like a table, but it is defined by a query on other views and 
base tables. The syntax for a view is 

CREATE VIEW <table name> [(<view column list>)] 

AS <query expression> 

[WITH CHECK OPTION ] 

Some of the behavior of views is expected. The stable name> must be different 
from the stable name> of any other sview definition> or stable definition> in the 
same schema to avoid confusion. The squery expression> must not contain any 
dynamic parameter specifications, so that the schema can figure out what is in a 
view when it is used without asking the user for parameter values at runtime. 

The number of scolumn name>s in the sview column list> must be the same as 
the squery expression^ the names and expressions are matched up position for 
position. If no sview column list> is given, then the view uses the scolumn name>s 
of the table specified by the squery expressions 


Joe Celko 


Joe Celko is a college teacher and consultant based in Los Angeles, as well as a 
member of the ANSI X3H2 Database Standards Committee. 













But watch out, because the same <column name> cannot 
be specified more than once in the <view column listx A join 
operation on two tables with the same names could duplicate 
a <column name>. If any two columns in the table specified 
by the <query expression> have the same <column name>, 
then you must specify a <view column list>. 

You can define a VIEW if and only if you have SELECT 
privileges on all the tables and views contained in the <query 
expressions You can see the security reasons for that rule. 

The <view definitions cannot contain a table reference to 
itself in the <query expressions This is not part of the current 


Table 1 

loan# 

region# 

appdate 

funddate 

1 

1 

1991-Apr-04 

1991-Apr-07 

2 

2 

1991-Apr-04 

1991-Apr-07 

3 

3 

1991-Apr-08 

1991-Apr-08 

4 

4 

1991-Mar-02 

1991-May-07 

5 

1 

1991-Mar-09 

1991-Apr-11 

6 

2 

1991-Apr-10 

NULL 

7 

3 

1991-Apr-10 

NULL 

8 

4 

1991 -Apr-10 

NULL 

9 

1 

1991-Apr-10 

NULL 

10 

1 

1991-Apr-10 

NULL 


Table 2 

region# 

COUNT(appdate) 

COUNT(funddate) 

1 

4 

2 

2 

2 

1 

3 

2 

1 

4 

1 

0 


Table 3 

loan# 

region# 

appdate 

funddate 

1 

1 

NULL 

1991-Apr-07 

1 

1 

1991-Apr-02 

NULL 

2 

2 

NULL 

1991-Apr-07 

2 

2 

1991-Apr-02 

NULL 

3 

3 

NULL 

1991-Apr-08 

3 

3 

1991-Apr-08 

NULL 

5 

1 

NULL 

1991-Apr-11 

6 

2 

1991-Apr-10 

NULL 

7 

3 

1991-Apr-10 

NULL 

8 

4 

1991-Apr-10 

NULL 

9 

1 

1991-Apr-10 

NULL 

10 

1 

1991-Apr-10 

NULL 


SQL standard, but will be in SQL2. You might want try to see 
what happens when you define CREATE VIEW SelfRef AS 
SELECT * FROM SelfRef; in your SQL implementation. My 
best guess is a virtual table with zero rows and columns will 
show up in the schema and the system will crash when you 
use it. 

The rules for updatable VIEWS are still being debated, thus 
I am going to ignore updates and assume that a VIEW is a 
read-only table. 

To get rid of a view use the statement DROP VIEW cview 
name>; and the database will do the housekeeping for you. 
The drop behavior will vary from product to product because 
a view can be built from other views. Most products will simp¬ 
ly go to a system catalog table, and remove the tuple which 
had the description of the view in it. If you try to drop a view 
that other views depend on, you will get an error message. 

The most common use for a view is security. The database 
administrator does not want the users to see confidential in¬ 
formation in the tables, so he creates a view without those 
columns. 

But a view can also be used for programming purposes. If 
you need to do a tricky join query, then it is easier to put it 
into a VIEW and invoke the VIEW as if it were a table. Here is 
an example of what you can and cannot do with VIEWS in a 
program. A certain loan company uses a table that looks like 
this: 

CREATE TABLE Loans 
(loan# PRIMARY KEY, 

region# INTEGER NOT NULL, 
appdate DATE, 
funddate DATE); 

The appdate is the date of the application and funddate is the 
date the loan was funded. Our goal is to get a report that 
gives the number of loan applications and funding in a given 
time period by region. For this article that time period is 1991 
April. It is possible that some loans will have a NULL funddate 
at the time of the report because they are still in process. The 
sample data is in Table 1. The average SQL programmer will 
know that this must be a grouped table and that the COUNT() 
function should be used to get the right number of loans. An 
experienced SQL programmer might use the COUNT(<column 
name>) function to automatically exclude the NULL values in 
<column name> before counting the number of rows. The first 
attempt might look like 

SELECT region#, COUNT(appdate), COUNT(funddate) 

FROM Loans 

WHERE appdate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
OR funddate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
GROUP BY region#; 

and give the results in Table 2. The results look reasonable, 
since the COUNT (appdate) column is always greater than the 
COUNT (funddate) column. The total number of regions is 
equal to the number of regions in the original table. The 
results look good, but are wrong! 
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The region #4 loans are (4, 8), and the funddate of loan #8 
is NULL. Loan #8 got counted in the appdate tally because its 
appdate is within the date range and excluded from the 
funddate tally because of the NULL value when the query 
was executed. Just what we wanted. 

The region #1 loans are (1, 5, 9, 10), but the appdate of 
loan #5 is not in the date range. It got counted because the 
funddate is within the date range and that preserved the row 
when the query was executed. Not what we wanted. 

This error could be avoided if the dates that are not in 
range were turned to NULLs before COUNT() processed them. 
But we cannot use an UPDATE statement to insert the nulls 
without destroying a lot of information. 

A better approach is to create views for the appdates by 
region and the funddates by region. We can produce the final 
report from a union of the two views. The two CREATE VIEU 
statements are in Listing 1. 

We can now use a UNION to put both of these VIEWS into 
one table and use that to generate the final report. That 
statement looks like this: 

SELECT * FROM appview 
UNION ALL 

SELECT * FROM fundview 
ORDER BY 1; 

The results of the UNION are just what we wanted for use 
with the COUNT() functions (see Table 3). Notice that loan #4 


does not appear since neither of its dates are within the 
search range. 

It would seem reasonable to then build a VIEU with the 
UNION as the <query expression^ so that we would have a 


Listing 1 

CREATE VIEW appview(1oan#, region#, appdate, funddate) 
AS SELECT loan#, region#, appdate, CAST DATE AS NULL 
FROM Loans 

WHERE appdate BETWEEN 1991-Apr-01 AND 1991-Apr-30; 
CREATE VIEW fundviewfloan#, region#, appdate, funddate) 
AS SELECT loan#, region#, CAST DATE AS NULL, funddate 
FROM Loans 

WHERE funddate BETWEEN 1991-Apr-01 AND 1991-Apr-30; 


Listing 2 

CREATE VIEW apptally(region#, appcount, fundcount) 

AS SELECT region#, COUNT(appdate), 0 
FROM Loans 

WHERE appdate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
GROUP BY region#; 

CREATE VIEW fundtallyfregion#, appcount, fundcount) 

AS SELECT region#, 0, COUNT(funddate) 

FROM Loans 

WHERE funddate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
GROUP BY region#; 

SELECT * FROM apptally 
UNION ALL 

SELECT * FROM fundtally 
ORDER BY 1; 
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single simple table. Too bad that this does not work. Most 
implementations of SQL use a table of pointers for the view, 
rather than materialize an actual table. The pointers point to 
rows in actual base tables or to other views, and make it 
much easier to update a view and save space in the session. 
If SQL allowed a union in a view definition, where would the 
pointers point when I had identical rows? 

Moreover, you often cannot use aggregate functions on 
views which have aggregated functions in them. An improved 
version of this same basic trick would use the aggregate func¬ 
tions in the view statements to avoid the double grouping 
problem, as in Listing 2. 

This approach has the advantage of directly giving the 
summary data for the report, as well as a smaller results table 
(see Table 4). This approach suggests the practical solution to 
the problem which should work in all implementations. Build 
a temporary table using the UNION statement in an INSERT 
INTO statement to load the table in the session. This table will 
be materialized, and can then be used by a program or 
another query without any problems. The code for this is 
straightforward (see Listing 3). 

Notice that the SELECT statements now have a constant 
zero, rather than a forced NULL value, in some of the rows. 
This will produce a result table without any NULL values in it, 
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so that a non-SQL report writer or COBOL program can imme¬ 
diately use the output without having to look at indicator 
variables (see Table 5). 

I tried to come up with an elaborate outer self-join 
among the Loans table, appview and fundview that would 
provide the same results as a UNION between appview and 
fundview. This effort was a failure, and even if it had worked, 
I fear that the execution time would have been prohibitive. 
The Outer join is not yet a part of standard SQL, so that 
solution would not have been portable. If you have an Outer 
join solution, please let me know. I offer a new SQL book as 
a prize for any new solutions to this problem. □ 


Listing 3 

CREATE TEMPORARY TABLE Temp 
(region# INTEGER NOT NULL, 
appcount INTEGER NOT NULL, 
fundcount INTEGER NOT NULL); 

INSERT INTO Temp (region#, appcount, fundcount) 
SELECT region#, COUNT(appdate), 0 
FROM Loans 

WHERE appdate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
GROUP BY region# 

UNION ALL 

SELECT region#, 0, COUNT(funddate) 

FROM Loans 

WHERE funddate BETWEEN 1991-Apr-01 AND 1991-Apr-30 
GROUP BY region# 

ORDER BY 1; 

SELECT region#, SUM(appcount), SUM(fundcount) 

FROM Temp 
GROUP BY region#; 


Table 4 

region# 

appcount 

fundcount 

1 

3 

NULL 

1 

NULL 

2 

2 

2 

NULL 

2 

NULL 

1 

3 

2 

NULL 

3 

NULL 

1 

4 

1 

NULL 


Table 5 

region# 

SUM(appcount) 

SUM(fundcount) 

1 

3 

2 

2 

2 

1 

3 

2 

1 

4 

1 

0 
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Programming Style 



Dan Saks 


Avoiding 

Unnecessary Preprocessing 


A Minor Correction 

In “All About Booleans" ( TECH Specialist, January 1991), I wrote that you can think 
of boolean in Pascal as an enumerated type 

type boolean = (false, true); 

so that 

true < false 

I wrote the inequality backwards. It should be 
false < true 
Oh, well. 

The C preprocessor is a handy tool. When used properly, it adds clarity, efficiency, 
and portability to C programs. Unfortunately, like many useful tools, it is easily 
abused. Poorly written preprocessor macros can cause insidious bugs. Overusing the 
preprocessor leads to maintenance and portability problems. (The international ob¬ 
fuscated C Programming Contest used to have a category for “Best Abuse of the 
Preprocessor,” but discontinued that category because it attracted a vastly dispropor¬ 
tionate share of the contest entries.) 

The C preprocessor is also part of C++. C++ includes several extensions to C that 
significantly reduce the need for preprocessing. Members of the ANSI C++ standards 
committee agree that good C++ programs avoid using the preprocessor as much as 
possible. In fact, some committee members would like to see the preprocessor 
omitted from the C++ standard, but I'm not quite sure just how serious they are. This 
sentiment is at odds with the committee's stated objective of minimizing incom¬ 
patibilities between C++ and C, and I see no indication that this extremist view will 
prevail. However, it's interesting (but not very surprising) that the preprocessor en¬ 
genders such intense feelings. 


Dan Saks is the owner of Saks & Associates, which offers consulting and training in 
C, C++ and Pascal. He is the secretary of the ANSI C++ committee and a member of the 
ANSI C committee. Readers are invited to send comments and suggestions to him at 
287 W. M cCreight Ave., Springfield, OH 45504 or by email at dsaks@wittenberg.edu. 

















Listing 1 

Idefine len 10 

int f(const char *str, size_t len); 

int g(void) 

( 

size_t len; 

if (len > max) 

len * max; 

i" 

/* End of File */ 


Listing 2 

int f(const char *str, size_t 10); 

int g(void) 

{ 

size_t 10; 

if (10 > max) 

10 = max; 

i" 

/* End of File */ 


Part of the problem with the C preprocessor is historical. 
Kernighan and Ritchie's early specification of the preprocessor 
in the first edition of The C Programming Language was ex¬ 
tremely terse, and in many ways incomplete. Consequently, 
different implementations had strikingly different behavior. 
The ANSI C committee labored for several years and success¬ 
fully reconciled many of the differences. Nonetheless, the C 
preprocessor still provides opportunities to introduce subtle 
bugs and maintenance problems. (P.J. Plauger[1][2][3] offers in¬ 
teresting insights into the early history of the preprocessor 
and describes its standardized behavior. Ellis and StroustrupI4] 
also provide examples of the behavior of different preproces¬ 
sors used by C and C++ compilers.) 

I’m not suggesting that you avoid preprocessing altogether. 
After all, it’s hard to imagine a non-trivial C or C++ program 
that doesn’t include at least one or two headers. However, I 
am suggesting that C programmers tend to overuse the 
preprocessor. Both Standard C, and especially C++, offer con¬ 
venient alternatives to some common uses for the preproces¬ 
sor. 

In this month’s column, I’ll describe some problems with 
using the preprocessor and suggest alternatives that avoid 
these pitfalls. This is not a tutorial on the preprocessor. I am 
assuming that you are already familiar with most of its fea¬ 
tures. 

Macros Know No Scope 

Representing arbitrary values as symbols is good program¬ 
ming practice. Traditional (K & R) C does not provide named 
compile-time constants, so c programmers typically use “ob¬ 
ject-like” macros (macros without arguments) to define sym¬ 
bolic constants. For example, 

#define BUF_MAX 100 
char buf[BUF_MAX]; 

if (i < BUF_MAX) 
buf [i ++] = c; 

is obviously better than 

char buf [100]; 

if (i < 100) 
buf [i ++] = c; 
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Using the symbol BUFJtAX everywhere 
adds clarity to each use. It also 
simplifies changing the value because 
you only need to change the value in 
one place (at the definition). 

Unfortunately, macro names don’t 
observe the scope rules followed by 
other identifiers in the C language 
proper. For example, in Listing 1, the 
macro name len substitutes 
everywhere it occurs in the prototype 
of function / and in the body of func¬ 
tion g. The preprocessor output shown 
in Listing 2 produces syntax errors. 

The lack of scope for macro names 
is a bigger problem in C++ because C++ 
has more complex scope rules than C. In C++, functions can be 
in the scope of classes, and classes can be in the scope of 
function or other classes. Consequently, C++ encourages you to 
use const definitions instead of tide fines. That is, instead of 

#define BUF_MAX 100 

you write 

const BUF_MAX = 100; 

C++ lets you use const identifiers in compile-time constant 
expressions. This means you can still use BUF_MAX to specify 
the dimension of an array, as in 

char buf[BUF_MAX]; 

Strictly speaking, you don’t need to specify the type of a 
const - it defaults to int. It’s better practice to always in¬ 
clude the type specifier, as in 

const int BUF_MAX = 100; 

Adding the type specifier forces me to consider the type of 
the constant. For reasons I gave in my last column (“just the 
Right Size”, TECH Specialist, March 1991), I think the type 
should be size_t and not int. For instance, 

const size_t BUF_MAX = 100; 

Since size t is an unsigned type, 

const BUF_MAX = lOOu; 

seems like an alternative way to get an unsigned constant, 
because lOOu is an unsigned value. However, a const object 
without an explicit type always defaults to int - it doesn’t 
take on the type of the assigned value as in Pascal or Moduia- 
2. This is not really a problem if the value of the constant is 
less than INT_MAX. However, you’ll run into portability 
problems if you write 

const BUF_MAX = 32768u; 
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on any architecture (like the PC) with 16-bit ints, BUFJIAX be¬ 
comes a ( signed) int constant with value -32768. You should 
write it as 

const size_t BUF_MAX = 32768u; 

Other Ways To Avoid #defines 

Although Standard C also lets you declare identifiers as 
const, it doesn't allow const identifiers in constant expres¬ 
sions. In C, you should consider using enumeration constants 
instead. Enumeration constants follow the scope rules, and 
you can use them in constant expressions. Thus, you can 
define BUF_NAX as an enumeration constant, and still use 
BUF_MAX to dimension an array, as in 


don’t work (it truncates the value to 3). In C, you must still 
write it as 

#define PI 3.1415926 

In C++, you write 

const double PI = 3.1415926; 

sizeof expressions offer another alternative that avoids defin¬ 
ing any symbolics constants. That is, instead of 

enum {BUF_MAX = 100}; 
char buf[BUF_MAX]; 


enum (BUF_MAX = 100); 
char buf[BUF_MAX]; 

The enum declaration has no tag name between the enum and 
the {, so it introduces no new type. The declaration defines a 
compile-time constant BUF__MAX whose value is 100. Enumera¬ 
tion values promote to type int when used in expressions, so 
BUF_MAX behaves like an integer constant. This coding style 
works in C++ as well as C. 

Using enumeration constants instead of # defines takes 
some getting used to, but I recommend that you try it. The 
only limitation on enumeration constants is that they always 
have type (signed) inf, so declarations like 


if (i < BUF_MAX) 
buf [i ++] = c; 

you forgo defining BUF_MAX and use sizeof (buf) in its place. 
The resulting code looks like: 

char buf[100]; 

if (i < sizeof(buf)) 
buf [i ++] = c; 

sizeof expressions are less convenient for arrays of elements 
whose size is not one. In this case, the dimension of the array 
is not the size of the array, but the size of the array divided 


enum {PI = 3.1415926}; 
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#define FOREVER for (;;) 

which you use to write loops that are in¬ 
finite, or that exit from the middle, as in 

FOREVER 

{ 

if (k == a[i]) 
break; 

by the size of each element. You can write a simple macro to . 

perform the calculation for you: 


Listing 3 

struct hn_port 
{ 

lifdef MSDOS 

int number; 

#else /* UNIX */ 

FILE *in, *out; 

lendif 

int errno; 

); 

/* End of File */ 


Listing 4 

lifdef ANSI 
linclude <stdio.h> 
lelse 

char *strcat(); 
char *strcpy(); 
lendif 

/* End of File */ 


Idefine DIM(a) \ 

(sizeof(a) / sizeof(a[0])) 

which you use as follows: 

int a[100]; 


Again, I think it's best to refrain from these indulgences. 

There’s an important difference between making largely 
cosmetic changes to a language and using macros to hide 
messy details or differences among compilers. For example, 
Plum and Brodie[5] explain that C compilers generally imple¬ 
ment loops that count down faster than loops that count up. 
Often, you can speed up a loop such as 


if (i < DIM(a)) 
a[i++] = c; 

I realize that I just suggested that you write a macro, at the 
same time I'm suggesting that you avoid writing macros. How¬ 
ever, this one macro may save you from defining many other 
macros. 

Making C Look Like... 

Newcomers to C often find C's use of curly brackets as 
compound statement delimiters unattractive. Many just ac¬ 
commodate to the new look; others try using the preproces¬ 
sor to make C look like the language they left behind. For 
example, macros like 

Idefine IF if ( 

Idefine THEN ) { 

Idefine ELSE } else { 

Idefine ENDIF } 

let you write C that looks like FORTRAN or Modula-2. There's 
more than one way to define these macros, and these styles 
can easily conflict. No one ever wins the ensuing holy wars, so 
I strongly discourage using such macros. To me, it generally 
indicates that the programmer hasn't yet learned to think in C. 

I confess that in the past, I've been guilty of writing macros 
like 

Idefine repeat do 

Idefine unti1(c) while (! (c)) 

I used to think Pascal's repeot-until statement was con¬ 
ceptually easier to handle than C's do-while. I grew up using 
repeat-until, and occasionally stumbled when I had to invert 
the logical condition to write a do-while. Still, I think it's best 
to learn to use the language as it appears, and not try to 
disguise it as something else. 

Another cute cosmetic use of the preprocessor is 


for (i = 1; i <= 10; ++i) 

by writing it as 

for (i = 10; i > 0; --i) 

It’s often even faster if you write the loop as 
for (i = 11; --i > 0;) 

The general form for a loop for all values of i from n down to 
1 is therefore 

for (i = (n) + 1; --i > 0; ) 

This is less readable than either of the first two loops. They 
recommend writing a macro 

Idefine L00PDN(i, n) \ 

for (i = (n) + 1; --i > 0; ) 

which you can use to write fairly readable loops like 

L00PDN(j, MAX) 

{ 

} 

I agree with this style of programming, and I don’t want to 
discourage it. Now that the C standard guarantees that macro 
names with up to 15 characters are portable, I might recom¬ 
mend using a slightly longer, more readable name like 
iOOP_mn. 

Conditional Compilation 

C programmers commonly use conditional compilation to 
write code that adapts to different environments. When the 
difference between environments can be embodied in only a 
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few lines of code, conditional compilation simplifies source 
code management. However, a source module composed lar¬ 
gely of conditional code sections is typically hard to read. 

For example, several years ago I wrote some communica¬ 
tions software that ran under both MS-DOS and UNIX[6]. Most 
of the source and header files were completely independent 
of the environment, and identical on both systems. The 
software manipulated serial ports as an abstract type called 
hn_port. Under DOS, an hn_port was declared as 

struct hn_port 

{ 

int number; 
int errno; 

}; 

Under UNIX, it was 

struct hn_port 

{ 

FILE *in, *out; 
int errno; 

}; 

Initiallly, I defined both forms of hn_port in a single header 
called hn_port.h, shown in Listing 3. This header uses Hf ... 
tiendif to select the form of the struct that's right for the 
current environment. If this had been the only difference be¬ 


tween the DOS and UNIX versions, I might have left it at that. 
However, as I wrote the software, I found more and more 
places to add conditional compilation, both in the headers and 
in the source files. The code became less readable with each 
added conditional. 

I ultimately broke the DOS and UNIX implementations into 
completely separate sets of source and header files. That is, I 
had one version of hn_port.h and hn_port.c for MS-DOS, and 
another for UNIX. I removed all conditional compilation based 
on the macros MSDOS and UNIX. And it was good. 

Listing 4 illustrates another common but often unnecessary 
use for conditional compilation. This code fragment declares 
standard string functions for both ANSI and non-ANSI C com¬ 
pilers. Rather than complicate all my portable application code, 
I prefer to create makeshift versions of the missing headers. 

For example, simply move all the declarations from be¬ 
tween the telse ... tendif in Listing 4 into your own 
header called string, h. Now, all you need in your application 
code is just 

#include <string.h> 

You no longer need the conditional. 

Writing your own headers takes a little extra effort up 
front, but it saves time in the long run, and produces shorter, 
cleaner code. I wrote a pair of articles in The C Users Journal 
last year that shows how to write your own versions of the 
most commonly used standard headers[7][8]. 
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Listing 5 

int find(const char *s) 

{ 

#ifdef DEBUG 

fprintf(stderr, "entering 
find\n“); 

#endif 


#ifdef DEBUG 

fprintf(stderr, "leaving 
find\n"); 

#endif 

} 

/* End of File */ 


Listing 6 


Listing 6 

lifdef DEBUG 

#define trace(p) 
fprintf (stderr, #p "\n") 

#else 

Idefine trace(p) ((void)O) 

#endif 


int find(const char *s) 

{ 

trace(entering find); 


trace(leaving find); 
} 

/* End of File */ 


Protective Wrappers 

Conditional compilation has some important uses for which 
I can find no alternative. I gave one example two months ago 
in my column on type size_t. The type sizet appears in 
several headers, like stdio.h and stdlib.h. size_t's declara¬ 
tion looks something like 

typedef unsigned size_t; 

You are allowed to include standard headers more than once, 
and in any order. However, neither C nor C++ lets you redefine 
a typedef, even if the definition is "benign” (token-by-token 
identical). Therefore, each header that defines size_t must put 
a protective wrapper around each definition, of the form 

#ifndef _SIZE_T_DEFINED 
#define _SIZE_T_DEFINED 
typedef unsigned size_t; 

#endif 


#define bool int 

However, typedefs are better because 
they observe the usual scopes rules, while 
macro names do not. 

Tracing And Debugging 

Conditional compilation is also useful 
for building diagnostics into your code. 
Placing each diagnostic inside an iif ... 
tendif lets you enable or disable the 
diagnostics by recompiling. Listing 5 il¬ 
lustrates the technique. Compiling the 
code with DEBUG defined turns the diag¬ 
nostics on; compiling without DEBUG turns 
them off. 

You can make the diagnostics less 
obtrusive by reducing the number of con¬ 
ditionals with the technique shown in List¬ 
ing 6. You simply use one conditional 
compilation group that defines the trace 
macro. If DEBUG is defined, then trace is defined to expand to 
a call to fprintf (). Otherwise, each trace call expands to a 
useless expression. 

Notice in Listing 6 that the argument to a call to the trace 
macro doesn’t have double quotes around its argument. The 
active form of the trace macro uses the stringizing operator # 
to convert the macro argument to a string literal by placing 
double quotes around it. The compiler concatenates adjacent 
string literals, so the following "\n" is joined to the result of 
#p. The Standard C assert macro uses a similar but more 
elaborate technique. 

The Bottom Line 

Go ahead and use the preprocessor. It serves some very 
important purposes. But don't use it any more than you must. 

Favor language features over preprocessor features. Con¬ 
solidate conditional compilation as much as possible. Use 
separate files when a single file has too many conditionals. 
Finally, don’t use macros to make cosmetic changes. □ 


In your own projects, you may find it convenient to declare 
project-wide types in more than one header. Each of those 
types should have its own protective wrapper. For example, 
you might define a Boolean type as 

#ifndef B00L_DEFINED 
#define BOOLJDEFINED 
typedef int bool; 

#endif 

You should not use a leading underscore in B00L_DEFINED be¬ 
cause the C standard reserves names beginning with a leading 
underscore followed by another underscore or a capital letter 
for use by the implementation. 

Standard C does permit benign macro redefinitions. That is, 
you can repeat a macro definition in the same compilation if 
each instance consists of the same sequences of tokens. Thus, 
you can avoid the protective wrapper if you write 
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Portability 


Portability is flexibility. If your programs are tied to one vendor’s compiler, you've 
just sold the soul of your software to someone else's schedules and capabilities. For 
example, programs built specifically for Microsoft C cannot (at this time) be converted 
unchanged to C++, since Microsoft has yet to introduce a C++ compiler. If you wrote 
programs that were specific to the Lattice compiler,which is now defunct, you have 
no choice but to rewrite them for another vendor’s compiler. And, while you may 
not see the need to port your programs to a non-DOS system today, the rapidly 
changing world of computers may hold a future in which you wish your programs 
were more portable. 

This article focuses on making your MS-DOS programs portable across the major 
PC C compilers: Borland C++ v2.0, Microsoft C V6.00A, WATCOM C v8.0, and Zortech C++ 
v3.0. Comments about Microsoft C apply to Quick C V2.51, and comments about 
Borland C++ are relevant to Turbo C++, 2nd Edition. 

Memory Models And Pointers 

When you compile a program with an MS-DOS C compiler, a memory model is 
specified that defines the default pointer type (and memory organization) for code 
and data elements. The memory model also defines whether your program will run 
in real or protected mode. In the case of Borland and Zortech, the memory model 
can also affect the way in which overlays are handled. The combination of all these 
options results in a surprising number of memory models, as shown in Table 1. 

A portable program must be designed for a portable memory model. Writing a 
program that requires the huge memory model, for example, will prevent it from 
being directly compiled with Zortech C++. On the other hand, relying upon one of 
Zortech's DOS-extended memory models will keep a program from being compatible 
with the Microsoft or Borland compilers. 


Scott Robert Ladd is a full-time free-lance writer with over 15 years computer 
programming experience. Scott works mostly in C and C++ when he’s not hiking and 
shooting photos with his wife and daughter. He can be contacted at 3652 County 
Road 730 Gunnison, CO 81230. 










Also, be wary of compiler-specific pointer types. Microsoft's 
based pointer type is unique; its use creates a program that 
can only be compiled with Microsoft C. If your program ex¬ 
plicitly defines huge pointers, it will not be compilable by Zor- 
tech C++. Similarly, handle pointers, which allow simplified ac¬ 
cess to expanded memory, are unique to Zortech C++. 

Structure Alignment 

A compiler can orient the members of a structure on byte 
(eight-bit), word (16-bit), and double-word (32-bit) boundaries. 
Filler characters are automatically added by the compiler be¬ 


tween members such that each member begins upon the 
specified boundary. For example, this structure 

struct foo_t 

{ 

char cl; 
char c2; 
word w; 

}; 


Table 1 


memory 

code pointer 

data pointer 

Borland C++ 

Microsoft C 

Watcom C 

Zortech C++ 

model 

size 

size 

V2.0 

V6.00A 

V8.0 

v3.0 

tiny 

near 

near 

yes 

yes 

yes 

yes 

small 

near 

near 

yes 

yes 

yes 

yes 

compact 

near 

far 

yes 

yes 

yes 

yes 

medium 

far 

near 

yes 

yes 

yes 

yes 

large 

far 

far 

yes 

yes 

yes 

yes 

huge 

huge 

huge 

yes 

yes 

yes 

no 

virtual 

* 

* 

yes 

no 

no 

yes 

286 extended 

prot 

prot 

no 

no 

no 

yes 

386 extended 

prot 

prot 

no 

no 

yes 

yes 


* The types of pointers used in virtual memory model are compiler-dependent. 


Compiler Memory Model Support 


alignment type 

Borland C++ v2.0 

Table 2 

Microsoft C V6.00A 

Watcom C v8.0 

Zortech C++ v3.0 

byte (8-bit) 

n/a 

/Zpl 

/zpl 

/al 

word (16-bit) 

/a 

/Zp2 

/zp2 

/a 2 

dword (32-bit) 

n/a 

/Zp4 

/zp4 

za4 

Alignment Switches 


alignment type 

Borland C++ v2.0 

Table 3 

Microsoft C v6.00A 

Watcom C v8.0 

Zortech C++ v3.0 

byte (8-bit) 

option -a- 

pack(l) 

pack (1) 

ZTC align 1 

word (16-bit) 

option -a 

pack(2) 

pack(2) 

ZTC align 2 

dword (32-bit) 

n/a 

pack(4) 

pack (4) 

ZTC align 4 

set to default 

option -a 

pack() 

pack() 

ZTC align 

Alignment Pragma 
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would have sizes of four, six, and 10 bytes when compiled 
respectively with byte, word, and double-word structure align¬ 
ment. With byte alignment, each element of the structure 
begins where the last member ended. When word alignment 
is used, odd-length members, such as single characters, are 
followed by a single filler byte. Word alignment forces each 
structure member to begin on a 16-bit boundary. Double- 
word alignment uses filler bytes to pad elements so that each 
element begins on a 32-bit boundary. 

The purpose of alignment is to make member access 
quicker. Members aligned on odd-byte boundaries require 
more time to load when using a 16-bit microprocessor. A 32- 
bit microprocessor can generally access elements located on 
32- bit boundaries more quickly than it can access elements 
with eight- and 16-bit alignment. It's a trade-off of increased 
size for quicker memory access. 

A compiler has a default alignment value. For Microsoft, 
Zortech, and Watcom, the default is word alignment. Borland, 
however, defaults to using byte alignment. If you write a pro¬ 
gram in Microsoft C that writes a structure to disk, the ele¬ 
ments of the structure will be aligned on word boundaries. If 
you recompile the program using Borland C++, and read the 
Microsoft-generated file in, the elements will be incorrect 
since Borland assumes byte alignment for structures. In addi¬ 
tion, Borland does not support 32-bit alignment. 


Each compiler supports a command-line switch to set the 
global alignment type for the files being compiled. These 
switches are summarized in Table 2. 

Within a program, a pragma can change the structure 
packing. Again, the pragmas for each compiler are different; 
Table 3 shows these pragmas. 

Each of the pragmas listed in Table 3 must be preceded by 
the #pragma keyword. The following statement tells the WAT¬ 
COM and Microsoft compilers to align all structures on 32-bit 
(double-word) boundaries: 

Ipragma pack(4) 

The set to default pragma option sets the structure 
alignment to the default value (which may have been 
changed by a command-line switch). Often, a structure may 
need to be packed with a specific alignment, regardless of the 
default alignment. The structure can be bracketed in align¬ 
ment pragmas to set a specific alignment and then restore 
the default alignment, as shown in Listing 1. 

Port I/O 

Your CPU's I/O ports can be directly accessed by special 
functions. Borland, however, uses a different set of function 
names than Microsoft, WATCOM, and Zortech. A simple set of 
macros can easily eliminate this problem, as shown in Listing 2. 


TCP/IP for Windows 



Network Windows™ Software Development Kit 


□ Three Application 
Programming Interfaces: 
Berkeley Sockets, Remote 
Procedure Call (RPC/XDR) 
and Network Windows 
(NFS client) 

□ Support for Microsoft 
Windows 3.0 in all modes: 
Real, Standard and 
Enhanced 

□ Shared library support in 
the form of small Dynamic 
Link Libraries (DLLs) 

□ May coexist with Novell 
Netware (Packet driver) 
or Microsoft LAN Manager 
(NDIS driver) 

□ Support for Ethernet and 
IBM Token Ring 


Supports C, C++ 
and Visual Basic 

NFS RPC 

Sockets $495 


For more information 
call: 

(408) 741 0781 
or fax: 


□ Works with network 
adapters from 3COM, 
Western Digital, IBM and 
others 

O Windows-based installation 

□ Three Windows applications 
included: 

♦ Network Configuration 

♦ Telnet-VTIOO 

♦ NFS Manager 



dfstmct 

Distinct Corporation 
P.O. Box 3410 Saratoga, CA 95070 


□ Request 336 on Reader Service Card □ 


Passive Backplane CPUs 

PC Tech manufactures a full line of modular passive 
backplane high performance PC compatible CPUs In ad¬ 
dition to Its line of 34010 and 34020 based video boards. 

Passive backplane based systems have many advantages, 
including ease of assembly, flexibility, fast service (by 
swapping boards), and simple upgrades to new or faster 
processors. 

Contact us for more information, pricing, and 
benchmark results. 

80386SX : 20 MHz, 512K through 16M DRAM 

80386DX: 25 MHz & 33 MHz, 1M - 32M DRAM, 

128K cache module optional 
80486: 25 MHz & 33 MHz, 1M - 32M DRAM, 

256K cache module optional 
Call, write, or FAX for complete specifications and retail 
or OEM terms. All PC Tech products are available in com¬ 
plete systems as well as components for retail, OEM, and 
private label sales. 


Designed, Manufactured, Sold and Serviced by: 



Voice . . .(612)345-4555 
FAX . . . .(612)345-5514 
Modem . .(612)345-4656 


907 N. 6th St., Lake City, MN 55041 


□ Request 116 on Reader Service Card □ 
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In-line Assembly Language 

In-line assembly language is inherently non-portable. A 
wise programmer builds assembly-language functions in a 
separate, linkable assembly-language module. In-line assembly 
language should only be used when the assembly statements 
are few and the overhead of a call to an external assembly 
language function is prohibitive. 

However, if you employ in-line assembly language, be 
aware of the differences between compilers. WATCOM does 
not support in-line assembly language. Borland and Microsoft 
support in-line assembly language using symbolic assembly- 
language instructions, but their syntax differs. Zortech uses the 
C++ asm pseudo-function to place bytes directly into your 
code. 

Function Libraries 

The only functions you can rely upon as portable are those 
defined by ANSI. While several other functions, such as in- 


Listing 1 

// Tell Borland C++ to use word alignment 
pragma option -a 

struct foo_t 
{ 

char cl; 
word w; 
char c2; 

}; 

// Reset alignment to default 
#pragma option -a. 


// End of File 


Alignment by Pragma 


Listing 2 

#if defined(_TURBOC_) 

linclude "dos.h 11 


#define IN PORT(port) 

inportb(port) 

Idefine IN PORTW(port) 

inport(port) 

Idefine OUT PORT(port,val) 

outportb(port,val) 

Idefine OUT PORTW(port,val) 
#else 

linclude "conio.h" 

outport(port.val) 

Idefine IN PORT(port) 

inp(port) 

Idefine IN PORTW(port) 

inpw(port) 

Idefine OUT PORT(port,val) 

outp(port,val) 

Idefine OUT PORTW(port,val) 
lendi f 

outpw(port,val) 

/* End of File */ 

Port I/O Function Macros 


tdos, are common to PC C compilers, most non-ANSI functions 
are unique to the compiler that implements them. WATCOM 
and Zortech have made an effort to duplicate the Microsoft 
function library. Borland, however, has a unique library. In 
most cases, conversion from one compiler to another will in¬ 
volve changing compiler-dependant function names and ad¬ 
justing parameter lists. 

Some differences in function libraries can be hidden 
through the use of macros. For example, the functions that 
read directories differ from compiler to compiler. By creating a 
simple structure and a set of macros, the differences between 
compilers can be shrouded. Listing 3 shows the structure and 
its associated macros. 

The FIND_FIRST and FIND_NEXT function macros are auto¬ 
matically defined to call the functions available with a specific 
compiler. The DOSFileData structure replaces the equivalent 
compiler-specific structures. 

Listing 3 shows how to use the compiler-identification 
macros generated by C compilers. Compiler-specific blocks of 
code can be bracketed by tif / tend if blocks, as is shown 
in the definitions of the macro functions in Listing 3. 

.OBJ Compatibility 

The record format of .OBJ files is the same for the four 
major C compilers. Some programmers assume that this will 
allow them to link an object module compiled with one com¬ 
piler to an object module generated by a different compiler. 
Alas, if only the world were so simple. Although the record 
naming and formatting of .OBJ files is the same for these 
compilers, the contents of the object records are different. 

Compilers generate calls to undocumented utility functions, 
which are stored in the standard function libraries. Multiplying 
two long values together will create an implicit function call. 
The long multiply function has a different name (and possibly 
a different calling convention) for each compiler. If an object 
module compiled with Microsoft C is linked into a program 
being compiled with Zortech C++, a call to Microsoft's long 
multiply function will generate an undefined external error 
from the Zortech linker. Why? Because the Zortech standard 
libraries don’t contain the Microsoft utility functions. 

In general, .OBJ and .LIB files are unique to the compiler 
that created them. True portability relies upon access to 
source code, so that programs can be completely regenerated 
for a new compiler. If you buy a function library from a third- 
party vendor, check to see which compilers they support. 
Avoid vendors who support a single compiler manufacturer, if 
portability is important. And, whenever possible, buy a source 
code license so that you can recompile with another compiler. 

Wrapping Up 

When creating portable applications, it's best to avoid the 
features specific to a vendor's implementation of C. Many of 
these features have been added by vendors to differentiate 
their product from the competition. A good programmer can 
usually find a technique for working around compiler-specific 
language extensions. □ 
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Listing 3 


Directory search macros and data structures 

DOSFileData MS-DOS file data structure 
FIND_FIRST MS-DOS function 0x4E — find first file 

FIND NEXT MS-DOS function 0x4F — find next file 


/* make sure the struct is packed on byte boundary */ 
#if defined(_MSC_VER) || defined(_QC) || 
defined (_WATCOMC_) 

Ipragma pack(l) 

lei if defined(_ZTC_) 

Ipragma align 1 
lei if defined(_TURB0C_) 

Ipragma option -a- 
lendif 


/* use this struct instead of compiler-defined file 
struct */ 
typedef struct 
{ 

char reserved[21]; 
char attrib; 
unsigned time; 
unsigned date; 
long size; 
char name [13]; 

) 

DOSFileData; 

/* set structure alignment to default */ 
lif defined (_MSC_VER) || defined(_QC) || 
defined (_WATC0MC_) 

Ipragma pack() 

lei if defined(_ZTC_) 

Ipragma align 

lei if defined(_TURBOC_) 

Ipragma option -a. 
lendif 

/* include proper header files and create macros */ 
lif defined(_MSC_VER) || defined(_QC) || 
defined (_WATCOMC_) 
linclude "direct.h“ 

Idefine FIND_FIRST(spec, attr, buf) \ 
_dos_findfirst(spec, attr, 

(struct find_t *)buf) 

Idefine FIND_NEXT(buf) _dos_findnext((struct 

find_t *)buf) 

lei if defined(_TURB0C_) 
linclude "dir.h” 

Idefine FIND_FIRST(spec, attr, buf) \ 

findfirst(spec, (struct ffblk *)buf, attr) 
Idefine FIND_NEXT(buf) \ 

findnext((struct ffblk *)buf) 

lei if defined(_ZTC_) 

linclude "dos.h" 


Idefine FIND_FIRST(spec, attr, buf) \ 
dos_findfirst(spec, attr, 

(struct D0S_FIND *)buf) 
Idefine FIND_NEXT(buf) dos_findnext((struct 

D0S_FIND *)buf) 


lendif 


/* End of File */ 


Directory Functions 


STOP 


...ERRORS! 




End your listing errors by subscribing to 
TECH Specialist’s code listings on disk. 



...HIGHER 

PRODUCTIVITY! 


Save hours of typing in long code listings 
and make better use of your time. 



Call 913-841-1631 TODAY! 

For only $30* you’ll receive 12 disks 
(one per issue) of TECH Specialist 
listings. You’ll save 50% off the price 
of buying the disks individually! 

If you don’t already subscribe 
to TECH Specialist-order both the 
magazine and disk for $59.* 


Subscriptions must be prepaid and 
are available on 5.25" or 3.5" 
MS-DOS format only. 


TECH. .. _ 
specialist 


2601 Iowa 

Lawrence, KS 66046 USA 


"foreign prices vary (call for details) 
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New Products 

Industry-Related News & Announcements 


Simulti Distributes PC Tasks 

Simulti is a parallel processing managment system for PC 
networks. It uses idle PCs connected to a network to process 
tasks in parallel, speeding up length jobs. Simulti does not re¬ 
quire a dedicated machine to manage parallel processing 
tasks. Once configured, a PC can act either as a master or as 
a slave. The user of a master PC can create any number of 
tasks; the first idle slave that detects a task executes it. 

You can immediately convert any master PC into a slave 
PC to add its processing power to the pool. You can also in¬ 
terrupt a slave PC at any time and the next available slave 
will take over the interrupted task. You define processing 


tasks either locally or globally (across the network) with 
simple script files. 

Simulti is designed to speed up jobs that can be broken 
into separate tasks. Examples of such tasks include large 
software compilations, processor-intensive applications, and 
I/O intensive applications. Simulti runs under DOS 3.3 or 
higher and Windows 3.0 and supports Novell Netware, LAN 
Manager and Lantastic. Simulti costs $195 per network. For 
more information, contact Parallex Software, 12021 Wil- 
shire Blvd., Suite 892, Los Angeles, CA 9002 5, (213) 826- 
6877. 


Blaise Releases View232 vl.1 

Blaise Computing Inc. has announced a new release of 
View232, a communications debugging tool. View232 turns a 
PC into a full-function communications dataline monitor. It al¬ 
lows users to see exactly what is happening on a com¬ 
munications line when using a modem, serial printer, or any 
other communications link. 

This new version can record transmitted data directly to 
disk. Users can also display the status of the hardware lines 
(RTS, CTS, DSR, and DTR) during an entire transmission. Ver¬ 
sion 1.1 now supports trigger and trap functions. Triggers 


allow you to detect and act on particular patterns in the 
data stream. You can program the trigger to start recording, 
stop recording, sound a beep, or timestamp the recorded 
data when the trigger detects the desired pattern. You can 
specify multiple triggers. 

The package includes source code, a manual, sample con¬ 
figuration files and sample program files. View232 vl.1 costs 
$189. For more information, contact Blaise Computing, Inc., 
819 Bancroft Way, Berkely, CA 94710, (415) 540-5441; 

FAX (415) 540-1938. 


JYACC Releases JAM For Windows 

JYACC has relased a Windows version of JAM, its 4GL ap¬ 
plication development tool.JAM/Presentation interface for 
Windows allows developers to build Windows applications 
with an authentic Windows look and feel. JAM'S Windows 
GUI supports unique Windows features such as the Windows 
multiple document interface, extended memory, pulldown 
and popup menus, radio buttons, checklists, dialog boxes, 
and the clipboard. Individual application windows as well as 
the application itself can be iconified. 

Page 74 - TECH Specialist 


By supporting multiple presentation environments, JAM 
allows developers to present their forms in graphical, charac¬ 
ter, or block-mode without recompilation. A form drawn in 
Windows and saved, for example, on a File server can be ac¬ 
cessed and used by character-based devices without any 
changes or reconfiguration. JAM/Presentation interface for 
Windows costs $395. For more information, contact JYACC, 
Inc., 116 John Street, New York, NY 10038, (212) 267-7722; 
FAX (212) 608-6753. 
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Butler Releases Screen Design Kit 

The Screen Design Kit is a package of software and acces¬ 
sories created to help programmers analyze, design, and 
maintain text screens. Screen Design Kit can be popped up 
inside any application, showing the coordinates (row and 
column) and the attribute byte (in many different formats) of 
any position on the screen. A color palette displays and 
describes every available color combination for both color 
and monochrome monitors simultaneously. The kit can 
quickly measure the height and width of any area on the 
screen. 

The package includes several accessories. A pad of 50 
screen design forms allows you to sketch a screen and im¬ 


mediately know the coordinates of every character on the 
screen. The pad comes with a row/column ruler. The pack¬ 
age also includes a laminated ASCII-decimal-hex-octal-binary 
reference chart showing every available character and sym¬ 
bol and all box-drawing combinations. A custom-designed 
binder provides storage for screen design forms and the 
other accessories. 

The kit works with any programming language in either 
standalone or TSR mode. The Screen Design Kit costs $99.95. 
For more information, contact Butler Computer Systems, 
P.O. Box 53 06, Walnut Creek, CA 94596, (415) 256-8401. 


Develop TCP/IP Windows Apps 

NetManage Inc. has released version 2.0 of NEWT-SDK, a 
TCP/IP Software Development Kit for Windows 3.0. NEWT is 
the only TCP/IP package implemented as a Windows DLL and 
not as a TSR. Windows loads the NEWT DLL into memory 
only when required, in contrast to a TSR, which resides in 
memory all the time, using between 80Kb and 150Kb of pre¬ 
cious 640Kb base memory. 

Release 2.0 of NEWT-SDK includes increased capacity-, the 
number of both IP and TCP concurrent sessions has doubled 
and file transfer time has decreased by as much as 30 per¬ 
cent This version now supports both Serial Line IP (TCP/IP net¬ 
work access via serial lines) and IP routing between 
networks, communicating with multiple network cards simul¬ 
taneously.. 

The new FTP DLL provides an interface to the Internet 
File Transfer Protocol (FTP) for file transfer to and from a 


remote system. NEWT also provides an FTP server with 
security. You can develop applications to copy, append, 
delete, and rename files as well as rename, create, and 
change directories on the remote host. The new SMTP DLL 
supports the Simple Mail Transfer Protocol, allowing a Win¬ 
dows 3.0 user to exchange mail with UNIX workstations, 

NEWT users, and other systems that support SMTP, such as 
IBM, DEC, Sun and HP. 

The package supports both standard and enhanced Win¬ 
dows modes and any network interface card based on the 
NDIS industry standard. NEWT-SDK 2.0 costs $500. Site licen¬ 
ses and quantity discounts for runtime NEWT are available. 

For more information, contact NetManage, Inc., 10020 N. De- 
Anza Blvd., #101, Cupertino, CA 95014, (408) 257-6404; 

FAX (408) 257-6405. 


Hard Drive Bible Describes Disks 

Corporate Systems Center has released Revision 3 of the 
Hard Drive Bible, a technical reference for hard disk drives. 
The Hard Drive Bible is a notebook bound, 196 page refer¬ 
ence manual that contains a brief history of disk drive tech¬ 
nology, definitions of the major interfaces and their 
specifications, setup and troubleshooting procedures for 
hundreds of disk drives, and a listing of available hard disks 
and their critical specifications. 

The manual comes with a diskette containing disk for¬ 
matting and a performance test program. The test program 


measures disk performance and compares it against industry 
standard systems such as IBM PS/2 and Compaq Systems. 

The resulting data from the test program is then automat¬ 
ically compiled into charts and graphics for visual interpreta¬ 
tion. 

The Hard Drive Bible (one manual and one diskette) costs 
$24.95 and is available at Computer Literacy Bookshops in 
California. For more information, contact Corporate Systems 
Center, 730 N. Pastoria Ave., Sunnyvale, CA 94086, (408) 
737-7312. 


AD3100 Samples At 200Khz 

Real Time Devices, Inc., has released the AD3100, a multi¬ 
function 12-bit PC bus data acquisition board that samples at 
200Khz and features a FIFO-based architecture. The AD3100 
offers eight differential analog input channels, an inde¬ 
pendent pacer clock, an on-board FIFO interface, DMA data 
transfer, dual 12-bit D/A conversion (optional) and four 
operating conversion modes. 

The AD3100 contains a 12-bit A/D converter and closely 
matched sample-and-hold circuit A programmable pacer 
clock controls the data acquisition rate and can be 
synchronized to an external reference signal for multiboard 
applications. Controlled by the pacer clock, A/D readings are 
automatically stored in the FIFO buffer for later transfer to 
the PC. The FIFO circuitry and DMA transfer capabilit extend 
the data acquisition range into the 200Khz region for signal 
and audio processing applications. 


The board supports four A/D conversion modes and four 
channel-select options, all configurable by software. Four 
programmable interval timers can be configured for counting 
or cascaded for timing functions. They can resolve time incre¬ 
ments down to 200 nanoseconds and can be configured to 
generate hardware interrupts, software-triggered strobes, 
event counters or programmable one-shots. 

The AD3100 is I/O mapped to one of 16 base I/O addres¬ 
ses and can be programmed from any high-level language. 
Each board includes a disk of example programs in BASIC 
Turbo Pascal, and Turbo C. The AD3100 costs $589. For more 
information, contact Real Time Devices, Inc., 820 N. Univer¬ 
sity Drive, P.O. Box 906, State College, PA 16804-0906, 
(814) 234-8087; FAX (814) 234-5218. 
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Readers' Forum 


We ask that letters with code listings be 
submitted in an ASCII text file on an MS- 
DOS formatted disk. Providing us an 
electronic copy of the code will prevent 
typographical errors that might result 
from optical scanning or re-keyboarding. 

Dear Sirs, 

Jerry Cigna's article in the June 1991 
issue was valuable to anyone having to 
migrate from the MS-DOS to the Win¬ 
dows programming environment. How¬ 
ever, he erred on page 53 when he 
said, “There is no easy way in Windows 
to communicate the usual command 
line to an application's mainf)." 

Mr. Cigna's difficulty may have come 
from a problem with the Microsoft SDK 
documentation. There is no mention in 
the indexes in that documentation of 
argc or argv. That is the tipoff to the 
experienced Microsoft victim that the 
topic is covered in detail in the indexed 
material. Mr. Cigna will work this out in 
time. 

The SDK Guide to Programming dis¬ 
cusses argc and argv on page 14-3. 
Now we reach Lesson Two of Mr. 
Cigna’s course of instruction: the 
documentation is wrong, according to 
the Microsoft Systems Journal (May 
1991, p. 135). It shows a single under¬ 
score in front of argc and argv. A 
double underscore is required. Also, MSJ 
says that argv must be declared as 
char** rather than the documented 
char*[]. MSJ also says that argvfO] 
returns some kernel thing rather than 
the program name that one would ex¬ 
pect. 

Borland appears to have read the 
SDK documentation in the required 
linear manner (clearing hurdle one) but 
believed it without testing it (tripping 
over hurdle two). Borland implements 
argc and _argv as documented by 
Microsoft. Worse, argvfO] returns the 
program path. 

Microsoft compatibility is a very dif¬ 
ficult thing. Maybe Borland can do bet¬ 
ter next time. 

Yours very truly, 

David P. Babcock 
111 Marquette Avenue South, Apt. 1312 
Minneapolis, MN 55401-2030 
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I assumed Jerry was talking about 
the fact that it is inconvenient for users 
to specify a command line. Editing a 
PIF file or walking through Program 
Manager menus for the privilege of 
typing the command line has pretty 
much discouraged me from the prac¬ 
tice. Your point is equally valid, of 
course — you can't get there from 
here with the faulty Microsoft 
documentation. 

From the tone of your letter, I take it 
that the SDK documentation has made 
you somewhat cynical. I have jumped 
up and down a couple of times myself 
when that documentation led me 
astray. In my saner moments, though, I 
have to admit that it is a large API to 
document and a very large percentage 
of the documentation is correct. If 
Microsoft would just maintain and free¬ 
ly distribute an errata sheet, I would 
have to claim that they are doing a 
good job of documenting the Windows 
API. -rib 


Dear Ron; 

Concerning Tom Carr's letter and 
your response on pages 85 and 86 of 
the June 1991 TECH Specialist, I've got to 
tell you how I feel - and what I want 
from your magazine. I, like Tom, have 
programmed for years in many lan¬ 
guages. Your answer indicates that you 
try to choose articles in specific lan¬ 
guages, the primary three apparently 
being C, assembly, and Pascal. 

I don't think in high-level languages, 
although I use them. I think in machine 
language. Judging from C being the 
most popular among your readers, 
probably most of them do, too. I'm 
given a programming problem. I decide 
how best to solve it based on what the 
hardware should do for me. Do I need 
pointers? Access to interrupts? The 
choice of a language then becomes 
simple. 

I do think that, as an editor, you 
should push your writers more towards 
the global view. We all are in the Intel 
camp, and the different languages all 
generate the same opcodes. As an ex¬ 
ample, take Jerry Cigna's excellent ar¬ 
ticle (p. 47). He discusses the Windows 


interface problem not in terms of what 
the hardware is doing (the global view), 
but in terms of what a C program must 
do (the local view). printfO just 
generates code; the problem isn't uni¬ 
que to C. Instead of being C-directed, I 
would have preferred a more generic 
view. If in his article Jerry had first 
presented each problem in terms of the 
hardware and then given the C code as 
a solution example, it would have been 
more valuable. Instead of saying “In 
Windows you have no getchf) func¬ 
tion" (p. 47), he could have used the re¬ 
lated DOS call which getchf) (or Read- 
Key, or Inkeyi, etc.) generates, and ex¬ 
plained why Windows doesn’t support 
it. This would be more valuable. 

As the editor, you can ask your 
writers for a little more "generality" in 
their submissions. 

Peter Skye 
The Los Angeles Method 
550 North Brand Boulevard, 7th Floor 
Glendale, CA 91203 

I think you have a good point and a 
bad example. I feel the whole point of 
Jerry's article was to provide a 
specific solution to a language- 
specific problem. If the article had 
consisted of generalities and simple 
examples, it would not have been so 
valuable. After all, many magazine ar¬ 
ticles have already described the 
general differences between DOS user 
interfaces and the Windows API. Jerry 
defined a specific problem (porting C 
programs that use standard I/O func¬ 
tions) and supplied a solution that is 
not just academic — you can use his 
code to save yourself quite a few 
hours of work. 

Since you use the phrase “your 
writers,” I should also point out that 
we have editors, managers, marketers, 
secretaries, and columnists, but we 
have no writers. In other words, the ar¬ 
ticles get written by programmers like 
yourself. Like most programming 
magazines (except the ones that are 
wall-to-wall advertisements), we 
depend on professional programmers, 
not professional writers, to provide the 
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Marketplace" 


MULTITASKING MSDOS 


Is your program scanning for 
keystrokes or other I/O events while 
analyzing data or displaying graphics? 

Convert your C program to a multitasked system 
overnight and simplify your job. IXOS, an 
MSDOS extension, converts functions into 
independent tasks for R/T and industrial control 
environments. 

80x86,80x87 & EMM support. Intertask 
messages and control. Preemptive scheduling. 
Selectable time slice periods. DOS critical error, 
Ctrl-C, Ctrl-Break handler. Divide by zero and 
80x87 exceptions stop offending task but not 
program. 

S100. 

Schneider Software Systems 

3430 List Place #1006 
Minneapolis, MN 55416 
612-926-7979 
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PostScript TSRs - Under 9K 
PSFX 3.0 TSR prints formatted output 
intended for Epson or IBM ProPrinter in 
PostScript. See Epson fonts, graphics, 
accents and boxes! Print portrait or land¬ 
scape, sizes up to 11x17. PostScript 
driver for databases, accounting, $85 
PSFXnet ' ovell NetWare version adds 
banner pages and keeps statistics on pages 
printed by user. $99 

EPScreen Captures PC screens as tiny 
Encapsulated PostScript (EPS) files, 
ready for manuals, frames optional. Font 
included. Color files less than 10 K. $95 

Legend Communications, Inc. 

54 Rosedale Avenue West 
Brampton, ON, Canada L6X 1K1 
30 day guarantee 

(416)450-1010 (800)668-7077 

Recommended by QMS, GCC, OCfi. 

□ Request 191 on Reader Service Card □ 
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SDLC OR X.25 SUPPORT 



ON THE PC 


30ft w "tj n H 

Use Sangoma SDLA card to provide 
cost effective, stable and easy to use 
SDLA or X.25 links from PCs running 
MS-DOS, UNIX, C-DOS etc. 



• Disk duplication 

• All formats 

All real time communication functions 


performed by intelligent coprocessor 
card and microcode without interrupt¬ 
ing the PC. 

• Four independent addresses in SDLC 
mode. 


• EVERLOCK copy protection 

• Label/sleeve printing 

• Full packaging services 

• Warehousing 

• Drop shipping 

• Up to 250 Logical Channels in X.25 


• Fulfillment 

mode. 


• 48-hour delivery 

• Full function SNA emulation pack¬ 
ages also available. 


• Consultation & guidance 

^Star-Byte, Inc. 

/^\ 2880 Bergey Rd Hatfield. PA 19440 

SangOma Technologies Inc. 


■a (416) 474-1990 


800 - 243-1515 
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Communications 2-paraiiei pons 

Problems? 

The compact Protocol 
Switch™ is designed to 
solve special commun¬ 
ications problems. There 
are 4 serial ports con¬ 
figurable in different ways: 

RS485 ports for long dis¬ 
tance, synchronous ports for high speed and RS232 
ports for IBM-PC interface. 2 parallel ports (32 bits) 
provide high speed bidirectional communications with 
the IBM-PC or standard PC printers. The Protocol Switch 
is easy to program with our low cost, interactive C 
development system. Battery backed memory, time of 
day clock, EEPROM. Use our box or embed the PC board 
in your product. Off-load PC communications using 
80,000 byte per second transfer via parallel port. Appli¬ 
cations: Change serial / parallel protocols. Implement 
another layer of security. Use for industrial control with 
our Opto 22 software support. From $295. 

Z-World Engineering 

1340 E. Covell Blvd. 

Davis, CA 95616 

Tel: (916) 753-3722 Fax: (916) 753-5141 
Automatic Fax: (916) 753-0618 
(Call from your fax, request data sheet #19.) 


□ Request 279 on Reader Service Card □ 


SMART™ & SMARTOOLS 


For Microsoft QuickBasic Programmers 

The professional BASIC programmer’s best friend. A 
fully integrated user interface to add as a front to run 
your application. Pick from Pull-Down, Pop-Up, 
Fill-the-Form type menus, and Dialogue boxes. 

Plus a full library of tools to use in your program, 
including mouse routines, pop-up message boxes and a 
lot more. 

SMARTmenu is transparent to the programmer, and 
will save you hours of work when developing your 
application. 

* Requires QB4.0 or later. 

* Demo available. 

Libraries + Manual $99 
For additional information call or write to: 

KALTEK 
P.O.Box 2166 
Martinez, CA 94553 
(415)370-1920 
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4-Serial Ports 
RS232 / 485 


ONE STOP 
SOFTWARE 
DUPLICATION 


❖ Disk & Tape Duplication 

❖ Documentation Printing 

❖ Package Assembly 

❖ Distributive Shipping 

❖ Bulk Disk & Tape Sales 

❖ Optical Media Duplication 

( 800 ) 222-0490 

FAX: (908) 462-5658 CD 

MEHppfo 

819 Route 33 V ) ^ 

Freehold, NJ 07728 
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DUPLICATION 

EQUIPMENT 


❖ Unattended Volume Duplication 
♦♦♦ PC Based & Standalone Units 

❖ Up to 180 disks/hour! 

❖ Easy Installation 

❖ Expandable & Field Upgradeable 

❖ Maintenance Contracts 

❖ CD ROM Development Systems 


( 800 ) 222-0490 
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raw material for the magazine. That 
may explain why the global view is 
often lacking. A lot of articles start out 
as a specific problem that a program¬ 
mer solves. TECH Specialist then be¬ 
comes a forum to share that solution 
with other programmers. 

Although I disagree with the ex¬ 
ample you picked, I think your idea 
about the global view is a good one. I 
think we do miss some opportunities 
to make some of the writing language- 
independent and incorporate the 
larger perspective. At a minimum, I will 
try to incorporate your idea into the 
next revision of our author's 
guidelines. Thank you for the thought¬ 
ful criticism, -rib 


Dear TECH Specialist, 

I am the representative of a very 
new, private Romanian company of 
consulting engineers and I write to ask 
your readers for help. 

After the Romanian revolution in 
December 1989, we considered that it 
was vital for Rumania to try and turn 
its economy from a bankrupt socialist 
system into a market-driven economy. 
One area where we realized desperate 
and particular attention needed to be 
paid was in computers and computing 
techniques. 

Twenty of our best software and 
hardware engineers from Constanta - 
drawn from computer centers, univer¬ 
sities and other enterprises - set up 
this agency. But the first major problem 


we face is a severe lack of scientific 
books, manuals, magazines and 
catalogues. 

We consider that one of the most 
effective means of ridding our country 
of the terrible memory of Communism 
is not simply by appealing for clothes 
and food, but for help in improving their 
education. That way we can improve 
our standards in industry and com¬ 
merce, and help our people to make 
the things they need for themselves. 

We would be very grateful if any of 
your readers would donate books and 
software, which is particularly expensive 
for us. Perhaps even make us a sub¬ 
scription to their favorite magazine, or 
even send us old issues that they no 
longer need. 


UPPER DECK EDITOR 

FOR WINDOWS 3.0 

A FAST, flexible, and robust text 
editor designed for the Windows 
environment. Edits files larger than 
64K. Regular expressions, search 
across multiple files, full 300-level 
UNDO, Windows clipboard sup¬ 
port, keyboard macros. Fully cus¬ 
tomizable. Introductory price $75 
plus $5 S/H (outside USA $15). CA 
residents please add sales tax. 30- 
day money-back guarantee. 

Upper Deck Systems 
P.O. Box 2751 
Escondido, CA 92033 
_ (619) 741-1075 _ 
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CopyControl 
COPY PROTECTION 


Control your profits with the copy protection designed 
with strength, user-transparency and compatibility. 

• Beats ALL the bit-copiers & Dis-assemblers 

• No hardware plugs or special disks required 

• Encrypts your program & adds anti-debug code 

• Allows you to produce full function demos 

• Compatible with LAN, backups & disk utilities 

• Supports all Floppy & Hard disk formats 

• Allows you to change parameters remotely. 
Control when, where, and how your software is ran. 
Compatible with all IBM/DOS Computers. 

$595 Unlimited Version, 30 day Money back guarantee 
imhi Also available by Meter Count (SSI 
BIB Free Demo & Info* COD *P0 


icrocosm Inc. 

Drawer 0, Wellington, MO 64097 

(800) 237-8400 ext. 212 
(816) 934-8384 / Fax (816) 934-2617 

□ Request 102 on Reader Service Card □ 
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THE CD-ROM 
DEVELOPER'S LAB 


Comprehensive CD-ROM multimedia 
production resource for PC ond Apple 
developers. Proven design, management, 
data prep programming, premastering 
and manufacturing techniques. Important 
specs from leading companies. Demos of 
off-the-self tools for imaging, audio and animation. 

Sample applications demonstrate the power of 
our source tools in C, Turbo Pascal. 

PC or MAC.® $395.00; 
Transportable version @ $425.00, 
Visa/MC accepted. 

SOFTWARE MART, INC. 

3933 Spicewood Springs Rd., Suite E-100 
Austin, Texas 78759 
(512) 346-7887 FAX: (512) 346-1393 


□ Request 310 on Reader Service Card □ 

LBARN *C WITH HASH Learn C with 
Audio Cassettes. LEARN WITH EASE allows 
the student to learn a language at their own 
pace. Learn at home or on the way to work. 
Easy to leant. Manual included. Beginning oi 
Advanced $69.95. C, C++, Basic, Pascal 
Fortran MASM and TASM avallible. 

FAST LIB Assembly Language Libraries. 
Over 300 ready to run Assembly Language 
routines for C, Pascal Basic or Fortran. 
5129.95 per Library. 

PRDriiT Send cmds to Laser or Dot Matrix 
printer. Make files with multiple cmds. $59.95 

As a full service Systems & Software organization, 
we offer Professional Programming and Training at 
reasonable rates. Call for more information. (415) 
43 9-3388 

Add $450 per item S/H CCA + 7%) VISA & M/C 

Orders (800) 284-8489 
LM Systems & Software 
P.O. Box 1606 Union City, CA 94587 
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C/ANALYST 2. 


B 


Can bring you up to speed quickly 
on unfamiliar C source code. 

ANALYZE performs PR0CTREE generates 

source code analysis large tree diagrams 

across multiple files. sideways. 

XREF generates a DATAFLOW shows how 

global cross reference data is passed between 

with read/write codes. modules. 

AM . FOR $250.00 

CALL FOR FREE 
ACTION DIAGRAMMER 
WITH DEMO OF C/ANALYST 

(503) 581-5622 


CATER SOFTWARE 


2182 Westfarthing Way NW 
Salem. OR 97304 
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The Make You’ve Been 
Waiting Fori 

Programmer's S UPEK -MA TNT<* 

The ‘easier’ make utility 

SUPER-MAINT builds your make and 
response flies, remembers your 
command flags, the make file name, 
and more!. SUPER-MAINTworks for 
you so you can focus where you need 
to: on your programming! Still only $55 
(2.50 s&h, NY residents add sales tax). 

Supports MS, Borland, Mix languages + More 



Shareware Evaluation Copy 
Available On Our BBS 


EmmaSoft 
PO Box 238 
Lansing, NY 14882 

Voice: (607)533-4685 
BBS: (607)533-7072 


m s 
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Thank you very much for publishing 
this appeal, we look forward to hearing 
from you soon. 

Please remember the old Chinese 
proverb which says: “Give a man a fish 
and you feed him for a day. Teach him 
to fish and you feed him for life.’’ 

Many thanks to you. 

Aurel Cartu, Manager, 
Consulting & Engineering Agency, 
Aleea Brindujelor Nr. 2, 
Bloc L9, 
Sc C, Ap 45, 
RO-8700 Constanta 
Romania 

As administrator of a non-profit as¬ 
sociation called AIDE (HELP in English), 


which stands for Assistance aux Infor- 
maticiens et Debutants Europeens, I 
was the person who received this ap¬ 
peal. With a mission to make it known 
to all and every one in the computing 
community, 1 went to Constanta at the 
end of March with some hardware and 
software. I can only say that your help 
will be most needed as, on April 1st, 
the prices have been multiplyed by 3 
while salaries only doubled 1 

If you prefer to deal with an oc¬ 
cidental person, please contact me and 
I will gladly do what I can. Also you 
may send the goods to this address as 
it is hazardous and time consuming to 
send directly to Rumania. (I think it is a 
good idea to send subscriptions to 
magazines and to do so directly to 
Aurel.) 


Cuilain Devillers, 
Administrator of A.I.D.E. 

P. 0. Box 54 
L-8001 Strassen 
Luxembourg 
Phone (+352) 312 721 
Fax (+352) 312 613 


I think we can at least cough up a 
free TECH Specialist subscription. I 
have managed to create a pretty big 
personal library just from magazines 
that individuals and companies were 
throwing away. How about it readers? 
If you or your company is just tossing 
those redundant subscriptions, why 
not put them to good use instead? -rib 


32-bit Protected Mode 
386 C Graphics Library 

Intel 386/486 C Code Builder, 
MicroWay, Watcom & Zortech 
with I’har Lap 3861 ASM 
Mixed Raster/Vector, 

Scalable, Rotatable Font, 
Viewports, Globa! Scaling 
VGA, SVGA, 8514/A, VESA, 
Hercules Graphics Station 
through 1024x768x256 (8-bit), 
640x480x32k (16-bit), 
512x480x16.7m (32-bit), 
WYSIWYG HP-GL/ PostScript 
$200 NO ROYALTIES 
FULL SOURCE CODE 
Gary R. Olhoeft 
P.O. Box 10870 Edgemont 
Golden, CO 80401-0620 
(303) 279-6345 or 877-3697 
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1:03 

TUB 

0:41 

is FASTEST! 



1 0:09 


RCS'“ 4.2 PVCS™ TUB™ 3.0 TUB™ 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TUB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 

TUB™ is BEST! 

"Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare" 
John Rex, Computer Language 
"TLIB is a great system" J. Vallino, PC Tech J 

. Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus™ MAKE & Slick " MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 

□ Request 137 on Reader Service Card □ 
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Transputer Education Kit 

for students, professionals, and hobbyists 

$396 

• PC add-in board including 20-MHz 32-bit T400 

transputer, PC interface, and 1 Mbyte memory 

• T400 C compiler and assembler 

• T400 Occam2 compiler and debugger 

• 1500 pages of documentation, including schematics 

• Example and demonstration programs 



CSA also carries a complete line of professional 
transputer products including boards, software develop¬ 
ment tools, and multi-user parallel processing systems 

Computer System Architects 

950 N. University Avenue • Provo, UT 84604 
(801) 374-2300 • 1-800-753-4CSA 
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Z-v\RCT0S 
SYSTEMS CORPORATION 

X-Port Parallel Adapter 

Expand mass store capabilities 

Attach CD-ROM and SCSI based 
peripherals to a single parallel port 

Comes with drivers for DOS, MSDEX 

Low power, compact size 

For notebooks, laptops, desktops 

$225 + shipping & handling 

PO, Cheque, VISA 

300 March Rd., 4th Floor, 

Kanata, Ontario, Canada, K2K 2E2 
(613) 591-3084 (613) 591-1806 (fax) 
Dealer & OEM enquiries welcomed 
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UNIQUE—your insider’s guide 
to the UNIX industry ' 


Every month Unique brings you: 

□ industry news and gossip 

□ market analyses 

□ unbiased, in-depth system and 
software reviews 

□ information on new startups and 
products 

Call (913) 841-1631 for your subscription. 
You’ll pay only $79 for a full year of the 
most complete insider news in 
UNIX and Xenix. 

R&D Publications, Inc. 

2601 Iowa St. 

Lawrence, KS 66046 
(913) 841-1631 
FAX: (913) 841-2624 


Is your product 
special? 

Is it so special only a 
programmer can 
understand it? 

Then advertise in 


the journal for programming specialists. 

Call (913)841-1631 today 

to reserve space 
for your ad. 

Ask for Jeff (Western Region), 
Donna (Midwestern Region), 
or Ed (Eastern Region) 


TECH. .. „ 

specialist 
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2601 Iowa St. 
Lawrence, KS 66046 
(913) 841-1631 FAX: (913) 841-2624 


FREE 

Product 

Information 

Use this postage paid 
card to stay up to date 
on products 
that affect 
your productivity. 

Just fill out the card at 
the right and 
drop it in the mail. 



TECH. .. „ 
specialist 


Please help us serve you by 
answering the following: 

1) I program: 

□ for a living 

□ as a hobby 

□ as a manager 


2) I program in: 

□ MS-DOS 

□ Macintosh 

□ Xenix/UNIX 


3) I program most frequently in: 

□ Assembly □ BASIC 

□ Pascal □ C 

□ Other_ 

□ Please send me subscription 

information. 
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CITYISTATEIZIP 


PHONE 


NO POSTAGE 
NECESSARY 
IF MAILED 
IN THE 

UNITED STATES 


BUSINESS REPLY MAIL 

FIRST CLASS MAIL PERMIT NO. 662 LAWRENCE. KS 
Postage will be paid by addressee 


TECH. .. . 
specialist. 


2601 Iowa St. 


Lawrence, KS 66046-9950 
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2601 Iowa St. 
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NO POSTAGE 
NECESSARY 
IF MAILED 
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FREE 

Product 

Information 


Use this postage paid 
card to stay up to date 
on products 
that affect 
your productivity. 


Just fill out the card at 
the right and 
drop it in the mail. 
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TECH. .. ... 
specialist_ 

□ YES! Send me 12 issues of TECH Specialist for only $29! 

□ 2 years (24 issues) for $54 □ 3 years (36 issues) for $77 

□ Bill Me □ Visa □ MasterCard 





Number_ Exp. 

Signature_ 


Name 


Company 


Address 

City 

State 


Zip 


Country/Province/Mailcode 

Please allow up to sixweeks for deliveiy of first issue. Orders outside the US must be prepaid in US funds. CAN ADA/MEXICO 2.8 
subscriptions are: 1 year - $38; 2 years - $63; 3 years - $86. Overseas subscriptions are: 1 year - $48; 2 years - $88; 3 years - $126. 




































COMPUTER 

LANGUAGE 


EHESME 

EEZE* 


BAT 


FIRST IMPRESSIONS LAST. 

INSTALL 3.0 GIVES YOUR SOFTWARE PRODUCT 
A PROFESSIONAL INTRODUCTION. 


Installation procedures that rely on 
batch files and DOS commands not 
only look amateurish but also have 
limited error handling capabilities. 
Today's users expect quality and ease 
of use from software — beginning the 
moment they open the package. A 
smooth, professional installation 
makes an important first impression. 

EVERYTHING YOU NEED 

INSTALL 3.0 is customized for your 
product with an ASCII text file called 
a "script file." INSTALL 3.0 comes 
with many sample script files that you 
can modify and use immediately. No 
programming is necessary to create 
most installations. However, C source 
code is included for your convenience 
and technical support is free. 

FAST AND SIMPLE 

Use INSTALL 3.0 to create an elegant 
installation procedure that will 
increase users' confidence in your 
product. INSTALL 3.0 takes advan¬ 
tage of available RAM for lightning- 
fast file transfers. All your documen¬ 
tation has to tell users is TYPE 
"A: INSTALL". 


INSTALL PRO 

• Builds distribution disk sets 
automatically 

• Creates a configuration file, 
containing all parameters for 
each disk set 

• Automatically builds INSTALL 
script files 

• Automatically formats disks 
(360K, 720K, 1.2M, 1.44M) 

• Uses a full screen, point-and- 
shoot interface for fast, efficient 
file tagging 

• Automatically splits large files 
across multiple diskettes 

• Literally cuts distribution disk 
building time from days to 
minutes for complex products 


Knowledge Dynamics 
Corporation 

Highway Contract 4, Box 185-H 
Canyon Lake, Texas (USA) 
78133-3508 
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PROVEN RELIABILITY 

INSTALL 3.0 has been used for over 
four years by some of the biggest (and 
smallest!) names in the industry, in 
the U.S. and abroad, to install millions 
of copies of their programs. Add your 
name to the list today. 

30 DAY MONEY-BACK 
GUARANTEE 

Free technical support. No royalties. 

MasterCard/VISA/COD/POs 

welcome. 

$399.95 INSTALL PRO 
$249.95 INSTALL 3.0 
$99.95 International Option 
$99.95 OS/2 Option 

SALES 

1/800-331-2783 ext. # 0194 

International 
1/512-964-3994 
24 hour FAX 1/512-964-3958 
24 hour BBS 1/512-964-3929 

CALL OR FAX BY NOON 
AND RECEIVE INSTALL 3.0 
TOMORROW! 







Interoperability. 
Platform Transparency. 
Distributed Workflow. 
Real WYSIWYG Type. 
X-Windows. 
Extended DOS. 
VCPI. 

Margaritas by the sea. 


It's just another beautiful day at the Quarterdeck API Conference. 

Attend our Fourth Annual API Conference for DESQview and DESQview/X 
developers and users. August 19-23 in Santa Monica, California. Join major corp¬ 
s's orations, VARs and developers in learning how to boost user productivity while 
saving big bucks. Hurry. Call or write today. The conference is filling up fast! 



Quarterdeck Office Systems, 150 Pico Blvd., Santa Monica, CA 90405 
(213) 392-9851 Fax (213) 399-3802 

□ Request 172 on Reader Service Card □ 




